Index of Section 1 Manual Pages
| Interix / SUA | gcc.1 | Interix / SUA |
gcc(1) gcc(1)
gcc
NAME
gcc - GNU project C and C++compiler
SYNOPSIS
gcc [-c|-S|-E] [-std=standard] [-g]
[-pg] [-Olevel] [-Wwarn...] [-pedantic]
[-Idir...] [-Ldir...] [-Dmacro[=defn]...]
[-Umacro] [-foption...] [-mmachine-option...]
[-o outfile] infile...
Only the most useful options are listed here; see below for the remainder.
g++ accepts mostly the same options as gcc.
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 -c option says not to run the linker.
Then the output consists of object files output by the assembler.
Other options are passed on to one stage of processing. Some options
control the preprocessor and others the compiler itself. Yet other options
control the assembler and linker; most of these are not documented here,
since you rarely need to use any of them.
Most of the command line options that you can use with GCC are useful for
C programs; when an option is only useful with another language (usually
C++), the explanation says so explicitly. If the description for a
particular option does not mention a source language, you can use that
option with all supported languages.
The gcc program accepts options and file names as operands. Many options
have multi-letter names; therefore multiple single-letter options may not
be grouped: -dr is very different from -d -r.
You can mix options and other arguments. For the most part, the order you
use doesn’t matter. Order does matter when you use several options
of the same kind; for example, if you specify -L more than once, the
directories are searched in the order specified.
Many options have long names starting with -f or with -W---for example, -
fforce-mem, -fstrength-reduce, -Wformat and so on. Most of these have both
positive and negative forms; the negative form of -ffoo would be -fno-foo.
This manual documents only one of these two forms, whichever one is not
the default.
OPTIONS
Option Summary
Here is a summary of all the options, grouped by type. Explanations are in
the following sections.
Overall Options
-c -S -E -o file -pipe -pass-exit-codes -x language -v -### --help --
target-help --version
C Language Options
-ansi -std=standard -aux-info filename -fno-asm -fno-builtin -fno-builtin-
function -fhosted -ffreestanding -fms-extensions -trigraphs -no-
integrated-cpp -traditional -traditional-cpp -fallow-single-precision -
fcond-mismatch -fsigned-bitfields -fsigned-char -funsigned-bitfields -
funsigned-char -fwritable-strings
C ++ Language Options
-fabi-version=n -fno-access-control -fcheck-new -fconserve-space -fno-
const-strings -fdollars-in-identifiers -fno-elide-constructors -fno-
enforce-eh-specs -fexternal-templates -falt-external-templates -ffor-scope
-fno-for-scope -fno-gnu-keywords -fno-implicit-templates -fno-implicit-
inline-templates -fno-implement-inlines -fms-extensions -fno-nonansi-
builtins -fno-operator-names -fno-optional-diags -fpermissive -frepo -fno-
rtti -fstats -ftemplate-depth-n -fuse-cxa-atexit -fvtable-gc -fno-weak -
nostdinC++ -fno-default-inline -Wabi -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
Objective-C Language Options
-fconstant-string-class=class-name -fgnu-runtime -fnext-runtime -gen-decls
-Wno-protocol -Wselector -Wundeclared-selector
Language Independent Options
-fmessage-length=n -fdiagnostics-show-location=[once|every-line]
Warning Options
-fsyntax-only -pedantic -pedantic-errors -w -W -Wall -Waggregate-return -
Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment -Wconversion -Wno-
deprecated-declarations -Wdisabled-optimization -Wno-div-by-zero -Werror -
Wfloat-equal -Wformat -Wformat=2 -Wformat-nonliteral -Wformat-security -
Wimplicit -Wimplicit-int -Wimplicit-function-declaration -Werror-implicit-
function-declaration -Wimport -Winline -Wno-endif-labels -Wlarger-than-len
-Wlong-long -Wmain -Wmissing-braces -Wmissing-format-attribute -Wmissing-
noreturn -Wno-multichar -Wno-format-extra-args -Wno-format-y2k -Wno-import
-Wnonnull -Wpacked -Wpadded -Wparentheses -Wpointer-arith -Wredundant-
decls -Wreturn-type -Wsequence-point -Wshadow -Wsign-compare -Wstrict-
aliasing -Wswitch -Wswitch-default -Wswitch-enum -Wsystem-headers -
Wtrigraphs -Wundef -Wuninitialized -Wunknown-pragmas -Wunreachable-code -
Wunused -Wunused-function -Wunused-label -Wunused-parameter -Wunused-value
-Wunused-variable -Wwrite-strings
C-only Warning Options
-Wbad-function-cast -Wmissing-declarations -Wmissing-prototypes -Wnested-
externs -Wstrict-prototypes -Wtraditional
Debugging Options
-dletters -dumpspecs -dumpmachine -dumpversion -fdump-unnumbered -fdump-
translation-unit[-n] -fdump-class-hierarchy[-n] -fdump-tree-original[-n] -
fdump-tree-optimized[-n] -fdump-tree-inlined[-n] -feliminate-dwarf2-dups -
fmem-report -fprofile-arcs -fsched-verbose=n -ftest-coverage -ftime-report
-g -glevel -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2 -ggdb -gstabs -
gstabs+ -gvms -gxcoff -gxcoff+ -p -pg -print-file-name=library -print-
libgcc-file-name -print-multi-directory -print-multi-lib -print-prog-
name=program -print-search-dirs -Q -save-temps -time
Optimization Options
-falign-functions=n -falign-jumps=n -falign-labels=n -falign-loops=n -
fbranch-probabilities -fcaller-saves -fcprop-registers -fcse-follow-jumps
-fcse-skip-blocks -fdata-sections -fdelayed-branch -fdelete-null-pointer-
checks -fexpensive-optimizations -ffast-math -ffloat-store -fforce-addr -
fforce-mem -ffunction-sections -fgcse -fgcse-lm -fgcse-sm -floop-optimize
-fcrossjumping -fif-conversion -fif-conversion2 -finline-functions -
finline-limit=n -fkeep-inline-functions -fkeep-static-consts -fmerge-
constants -fmerge-all-constants -fmove-all-movables -fnew-ra -fno-branch-
count-reg -fno-default-inline -fno-defer-pop -fno-function-cse -fno-guess-
branch-probability -fno-inline -fno-math-errno -fno-peephole -fno-
peephole2 -funsafe-math-optimizations -ffinite-math-only -fno-trapping-
math -fno-zero-initialized-in-bss -fomit-frame-pointer -foptimize-
register-move -foptimize-sibling-calls -fprefetch-loop-arrays -freduce-
all-givs -fregmove -frename-registers -freorder-blocks -freorder-functions
-frerun-cse-after-loop -frerun-loop-opt -fschedule-insns -fschedule-insns2
-fno-sched-interblock -fno-sched-spec -fsched-spec-load -fsched-spec-load-
dangerous -fsignaling-nans -fsingle-precision-constant -fssa -fssa-ccp -
fssa-dce -fstrength-reduce -fstrict-aliasing -ftracer -fthread-jumps -
funroll-all-loops -funroll-loops --param name=value -O -O0 -O1 -O2 -O3 -Os
Preprocessor Options
-$ -Aquestion=answer -A-question[=answer] -C -dD -dI -dM -dN -
Dmacro[=defn] -E -H -idirafter dir -include file -imacros file -iprefix
file -iwithprefix dir -iwithprefixbefore dir -isystem dir -M -MM -MF -MG -
MP -MQ -MT -nostdinc -P -remap -trigraphs -undef -Umacro -Wp,option
Assembler Option
-Wa,option
Linker Options
object-file-name -llibrary -nostartfiles -nodefaultlibs -nostdlib -s -
static -static-libgcc -shared -shared-libgcc -symbolic -Wl,option -Xlinker
option -u symbol
Directory Options
-Bprefix -Idir -I- -Ldir -specs=file
Target Options
-V version -b machine
Machine Dependent Options
i386 and x86-64 Options -mcpu=cpu-type -march=cpu-type -mfpmath=unit -
masm=dialect -mno-fancy-math-387 -mno-fp-ret-in-387 -msoft-float -msvr3-
shlib -mno-wide-multiply -mrtd -malign-double -mpreferred-stack-
boundary=num -mmmx -msse -msse2 -m3dnow -mthreads -mno-align-stringops -
minline-all-stringops -mpush-args -maccumulate-outgoing-args -m128bit-
long-double -m96bit-long-double -mregparm=num -momit-leaf-frame-pointer -
mno-red-zone -mcmodel=code-model -m32 -m64
Code Generation Options
-fcall-saved-reg -fcall-used-reg -ffixed-reg -fexceptions -fnon-call-
exceptions -funwind-tables -fasynchronous-unwind-tables -finhibit-size-
directive -finstrument-functions -fno-common -fno-ident -fno-gnu-linker -
fpcc-struct-return -fpic -fPIC -freg-struct-return -fshared-data -fshort-
enums -fshort-double -fshort-wchar -fvolatile -fvolatile-global -
fvolatile-static -fverbose-asm -fpack-struct -fstack-check -fstack-limit-
register=reg -fstack-limit-symbol=sym -fargument-alias -fargument-noalias
-fargument-noalias-global -fleading-underscore -ftls-model=model -ftrapv -
fbounds-check
Options Controlling the Kind of Output
Compilation can involve up to four stages: preprocessing, compilation
proper, assembly and linking, always in that order. The first three stages
apply to an individual source file, and end by producing an object file;
linking combines all the object files (those newly compiled, and those
specified as input) into an executable file.
For any given input file, the file name suffix determines what kind of
compilation is done:
file.c
C source code which must be preprocessed.
file.i
C source code which should not be preprocessed.
file.ii
C ++ source code which should not be preprocessed.
file.m
Objective-C source code. Note that you must link with the library
libobjc.a to make an Objective-C program work.
file.mi
Objective-C source code which should not be preprocessed.
file.h
C header file (not to be compiled or linked).
file.cc
file.cp
file.cxx
file.cpp
file.C++
file.C
C ++ source code which must be preprocessed. Note that in .cxx, the
last two letters must both be literally x. Likewise, .C refers to a
literal capital C.
file.f
file.for
file.FOR
Fortran source code which should not be preprocessed.
file.F
file.fpp
file.FPP
Fortran source code which must be preprocessed (with the traditional
preprocessor).
file.r
Fortran source code which must be preprocessed with a RATFOR
preprocessor (not included with GCC ).
file.ads
Ada source code file which contains a library unit declaration (a
declaration of a package, subprogram, or generic, or a generic
instantiation), or a library unit renaming declaration (a package,
generic, or subprogram renaming declaration). Such files are also
called specs.
file.adb
Ada source code file containing a library unit body (a subprogram or
package body). Such files are also called bodies.
file.s
Assembler code.
file.S
Assembler code which must be preprocessed.
other
An object file to be fed straight into linking. Any file name with no
recognized suffix is treated this way.
You can specify the input language explicitly with the -x option:
-x none
Turn off any specification of a language, so that subsequent files are
handled according to their file name suffixes (as they are if -x has
not been used at all).
-pass-exit-codes
Normally the gcc program will exit with the code of 1 if any phase of
the compiler returns a non-success return code. If you specify -pass-
exit-codes, the gcc program will instead return with numerically
highest error produced by any phase that returned an error indication.
If you only want some of the stages of compilation, you can use -x (or
filename suffixes) to tell gcc where to start, and one of the options -c,
-S, or -E to say where gcc is to stop. Note that some combinations (for
example, -x cpp-output -E) instruct gcc to do nothing at all.
-c
Compile or assemble the source files, but do not link. The linking
stage simply is not done. The ultimate output is in the form of an
object file for each source file.
By default, the object file name for a source file is made by replacing
the suffix .c, .i, .s, etc., with .o.
Unrecognized input files, not requiring compilation or assembly, are
ignored.
-S
Stop after the stage of compilation proper; do not assemble. The
output is in the form of an assembler code file for each non-assembler
input file specified.
By default, the assembler file name for a source file is made by replacing
the suffix .c, .i, etc., with .s.
Input files that don't require compilation are ignored.
-E
Stop after the preprocessing stage; do not run the compiler proper.
The output is in the form of preprocessed source code, which is sent
to the standard output.
Input files which don't require preprocessing are ignored.
-o file
Place output in file file. This applies regardless to whatever sort of
output is being produced, whether it be an executable file, an object
file, an assembler file or preprocessed C code.
Since only one output file can be specified, it does not make sense to
use -o when compiling more than one input file, unless you are
producing an executable file as output.
If -o is not specified, the default is to put an executable file in
a.out, the object file for source.suffix in source.o, its assembler
file in source.s, and all preprocessed C source on standard output.
-v
Print (on standard error output) the commands executed to run the
stages of compilation. Also print the version number of the compiler
driver program and of the preprocessor and the compiler proper.
-###
Like -v except the commands are not executed and all command arguments
are quoted. This is useful for shell scripts to capture the driver-
generated command lines.
-pipe
Use pipes rather than temporary files for communication between the
various stages of compilation. This fails to work on some systems
where the assembler is unable to read from a pipe; but the GNU
assembler has no trouble.
--help
Print (on the standard output) a description of the command line
options understood by gcc. If the -v option is also specified then --
help will also be passed on to the various processes invoked by gcc,
so that they can display the command line options they accept. If the
-W option is also specified then command line options which have no
documentation associated with them will also be displayed.
--target-help
Print (on the standard output) a description of target specific
command line options for each tool.
--version
Display the version number and copyrights of the invoked GCC.
Compiling C ++ Programs
C ++ source files conventionally use one of the suffixes .C, .cc, .cpp,
.C++, .cp, or .cxx; preprocessed C++files use the suffix .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 gcc).
However, C ++ programs often require class libraries as well as a compiler
that understands the C++language---and under some circumstances, you might
want to compile programs from standard input, or otherwise without a
suffix that flags them as C ++ programs. 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, g++ is also installed with the
name C++.
When you compile C ++ programs, you may specify many of the same command-
line options that you use for compiling programs in any language; or
command-line options meaningful for C and related languages; or options
that are meaningful only for C ++ programs.
Options Controlling C Dialect
The following options control the dialect of C (or languages derived from
C, such as C ++ and Objective-C) that the compiler accepts:
-ansi
In C mode, support all ISO C90 programs. In C ++ mode, remove GNU
extensions that conflict with ISO C ++.
This turns off certain features of GCC that are incompatible with ISO C90
(when compiling C code), or of standard C ++ (when compiling C ++ code),
such as the asm and typeof keywords, and predefined macros such as unix
and vax that identify the type of system you are using. It also enables
the undesirable and rarely used ISO trigraph feature. For the C compiler,
it disables recognition of C++style // comments as well as the inline
keyword.
The alternate keywords __asm__, __extension__, __inline__ and __typeof__
continue to work despite -ansi. You would not want to use them in an ISO C
program, of course, but it is useful to put them in header files that
might be included in compilations done with -ansi. Alternate predefined
macros such as __unix__ and __vax__ are also available, with or without -
ansi.
The -ansi option does not cause non-ISO programs to be rejected
gratuitously. For that, -pedantic is required in addition to -ansi.
The macro __STRICT_ANSI__ is predefined when the -ansi option is used.
Some header files may notice this macro and refrain from declaring certain
functions or defining certain macros that the ISO standard doesn't call
for; this is to avoid interfering with any programs that might use these
names for other things.
Functions which would normally be built in but do not have semantics
defined by ISO C (such as alloca and ffs) are not built-in functions with
-ansi is used.
-std=
Determine the language standard. This option is currently only supported
when compiling C or C ++. A value for this option must be provided;
possible values are:
c89
iso9899:1990
ISO C90 (same as -ansi).
iso9899:199409
ISO C90 as modified in amendment 1.
c99
c9x
iso9899:1999
iso9899:199x
ISO C99. Note that this standard is not yet fully supported; see
for more information. The
names c9x and iso9899:199x are deprecated.
gnu89
Default, ISO C90 plus GNU extensions (including some C99 features).
gnu99
gnu9x
ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC,
this will become the default. The name gnu9x is deprecated.
C++98
The 1998 ISO C ++ standard plus amendments.
gnu++98
The same as -std=C++98 plus GNU extensions. This is the default for
C++code.
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 __restrict__ even when -
std=c99 is not specified.
The -std options specifying some version of ISO C have the same effects as
-ansi, except that features that were not in ISO C90 but are in the
specified version (for example, // comments and the inline keyword in ISO
C99) are not disabled.
-aux-info filename
Output to the given filename prototyped declarations for all functions
declared and/or defined in a translation unit, including those in header
files. This option is silently ignored in any language other than C.
Besides declarations, the file indicates, in comments, the origin of each
declaration (source file and line), whether the declaration was implicit,
prototyped or unprototyped (I, N for new or O for old, respectively, in
the first character after the line number and the colon), and whether it
came from a declaration or a definition (C or F, respectively, in the
following character). In the case of function definitions, a K&R-style
list of arguments followed by their declarations is also provided, inside
comments, after the declaration.
-fno-asm
Do not recognize asm, inline or typeof as a keyword, so that code can use
these words as identifiers. You can use the keywords __asm__, __inline__
and __typeof__ instead. -ansi implies -fno-asm.
In C ++, this switch only affects the typeof keyword, since asm and inline
are standard keywords. You may want to use the -fno-gnu-keywords flag
instead, which has the same effect. In C99 mode (-std=c99 or -std=gnu99),
this switch only affects the asm and typeof keywords, since inline is a
standard keyword in ISO C99.
-fno-builtin
-fno-builtin-function
Don't recognize built-in functions that do not begin with __builtin_ as
prefix.
GCC normally generates special code to handle certain built-in functions
more efficiently; for instance, calls to alloca may become single
instructions that adjust the stack directly, and calls to memcpy may
become inline copy loops. The resulting code is often both smaller and
faster, but since the function calls no longer appear as such, you cannot
set a breakpoint on those calls, nor can you change the behavior of the
functions by linking with a different library.
With the -fno-builtin-function option only the built-in function function
is disabled. function must not begin with __builtin_. If a function is
named this is not built-in in this version of GCC, this option is ignored.
There is no corresponding -fbuiltin-function option; if you wish to enable
built-in functions selectively when using -fno-builtin or -ffreestanding,
you may define macros such as:
#define abs(n) __builtin_abs ((n))
#define strcpy(d, s) __builtin_strcpy ((d), (s))
-fhosted
Assert that compilation takes place in a hosted environment. This implies
-fbuiltin. A hosted environment is one in which the entire standard
library is available, and in which main has a return type of int. Examples
are nearly everything except a kernel. This is equivalent to -fno-
freestanding.
-ffreestanding
Assert that compilation takes place in a freestanding environment. This
implies -fno-builtin. A freestanding environment is one in which the
standard library may not exist, and program startup may not necessarily be
at main. The most obvious example is an OS kernel. This is equivalent to -
fno-hosted.
-fms-extensions
Accept some non-standard constructs used in Microsoft header files.
-trigraphs
Support ISO C trigraphs. The -ansi option (and -std options for strict ISO
C conformance) implies -trigraphs.
-no-integrated-cpp
Performs a compilation in two passes: preprocessing and compiling. This
option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the -
B option. The user supplied compilation step can then add in an additional
preprocessing step after normal preprocessing but before compiling. The
default is to use the integrated cpp (internal cpp).
The semantics of this option will change if "cc1", "cc1plus", and "cc1obj"
are merged.
-traditional
-traditional-cpp
Formerly, these options caused GCC to attempt to emulate a pre-standard C
compiler. They are now only supported with the -E switch. The preprocessor
continues to support a pre-standard mode. See the GNU CPP manual for
details.
-fcond-mismatch
Allow conditional expressions with mismatched types in the second and
third arguments. The value of such an expression is void. This option is
not supported for C++.
-funsigned-char
Let the type char be unsigned, like unsigned char.
Each kind of machine has a default for what char should be. It is either
like unsigned char by default or like signed char by default.
Ideally, a portable program should always use signed char or unsigned char
when it depends on the signedness of an object. But many programs have
been written to use plain char and expect it to be signed, or expect it to
be unsigned, depending on the machines they were written for. This option,
and its inverse, let you make such a program work with the opposite
default.
The type char is always a distinct type from each of signed char or
unsigned char, even though its behavior is always just like one of those
two.
-fsigned-char
Let the type char be signed, like signed char.
Note that this is equivalent to -fno-unsigned-char, which is the negative
form of -funsigned-char. Likewise, the option -fno-signed-char is
equivalent to -funsigned-char.
-fsigned-bitfields
-funsigned-bitfields
-fno-signed-bitfields
-fno-unsigned-bitfields
These options control whether a bit-field is signed or unsigned, when the
declaration does not use either signed or unsigned. By default, such a
bit-field is signed, because this is consistent: the basic integer types
such as int are signed types.
-fwritable-strings
Store string constants in the writable data segment and don't uniquize
them. This is for compatibility with old programs which assume they can
write into string constants.
Writing into string constants is a very bad idea; "constants" should be
constant.
Options Controlling C++ Dialect
This section describes the command-line options that are only meaningful
for C++ programs; but you can also use most of the GNU compiler options
regardless of what language your program is in. For example, you might
compile a file firstClass.C like this:
g++ -g -frepo -O -c firstClass.C
In this example, only -frepo is an option meant only for C++ programs; you
can use the other options with any language supported by GCC.
Here is a list of options that are only for compiling C++ programs:
-fabi-version=n
Use version n of the C++ ABI. Version 1 is the version of the C++ ABI
that first appeared in G++ 3.2. Version 0 will always be the version
that conforms most closely to the C++ ABI specification. Therefore,
the ABI obtained using version 0 will change as ABI bugs are fixed.
The default is version 1.
-fno-access-control
Turn off all access checking. This switch is mainly useful for working
around bugs in the access control code.
-fcheck-new
Check that the pointer returned by operator new is non-null before
attempting to modify the storage allocated. This check is normally
unnecessary because the C++ standard specifies that operator new will
only return 0 if it is declared throw(), in which case the compiler
will always check the return value even without this option. In all
other cases, when operator new has a non-empty exception
specification, memory exhaustion is signalled by throwing std::
bad_alloc. See also new (nothrow).
-fconserve-space
Put uninitialized or runtime-initialized global variables into the
common segment, as C does. This saves space in the executable at the
cost of not diagnosing duplicate definitions. If you compile with this
flag and your program mysteriously crashes after main() has completed,
you may have an object that is being destroyed twice because two
definitions were merged.
This option is no longer useful on most targets, now that support has
been added for putting variables into BSS without making them common.
-fno-const-strings
Give string constants type char * instead of type const char *. By
default, G++ uses type const char * as required by the standard. Even
if you use -fno-const-strings, you cannot actually modify the value of
a string constant, unless you also use -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 const char *.
-fdollars-in-identifiers
Accept $ in identifiers. You can also explicitly prohibit use of $
with the option -fno-dollars-in-identifiers. (GNU C allows $ by
default on most target systems, but there are a few exceptions.)
Traditional C allowed the character $ to form part of identifiers.
However, ISO C and C++forbid $ in identifiers.
-fno-elide-constructors
The C++ standard allows an implementation to omit creating a temporary
which is only used to initialize another object of the same type.
Specifying this option disables that optimization, and forces G++ to
call the copy constructor in all cases.
-fno-enforce-eh-specs
Don't check for violation of exception specifications at runtime. This
option violates the C++standard, but may be useful for reducing code
size in production builds, much like defining NDEBUG. The compiler
will still optimize based on the exception specifications.
-fexternal-templates
Cause #pragma interface and implementation to apply to template
instantiation; template instances are emitted or not according to the
location of the template definition.
This option is deprecated.
-falt-external-templates
Similar to -fexternal-templates, but template instances are emitted or
not according to the place where they are first instantiated.
This option is deprecated.
-ffor-scope
-fno-for-scope
If -ffor-scope is specified, the scope of variables declared in a for-
init-statement is limited to the for loop itself, as specified by the
C++standard. If -fno-for-scope is specified, the scope of variables
declared in a for-init-statement extends to the end of the enclosing
scope, as was the case in old versions of G++, and other (traditional)
implementations of C++.
The default if neither flag is given to follow the standard, but to
allow and give a warning for old-style code that would otherwise be
invalid, or have different behavior.
-fno-gnu-keywords
Do not recognize typeof as a keyword, so that code can use this word
as an identifier. You can use the keyword __typeof__ instead. -ansi
implies -fno-gnu-keywords.
-fno-implicit-templates
Never emit code for non-inline templates which are instantiated
implicitly (i.e. by use); only emit code for explicit instantiations.
-fno-implicit-inline-templates
Don't emit code for implicit instantiations of inline templates,
either. The default is to handle inlines differently so that compiles
with and without optimization will need the same set of explicit
instantiations.
-fno-implement-inlines
To save space, do not emit out-of-line copies of inline functions
controlled by #pragma implementation. This will cause linker errors if
these functions are not inlined everywhere they are called.
-fms-extensions
Disable pedantic warnings about constructs used in MFC, such as
implicit int and getting a pointer to member function via non-standard
syntax.
-fno-nonansi-builtins
Disable built-in declarations of functions that are not mandated by
ANSI/ISO C. These include ffs, alloca, _exit, index, bzero, conjf, and
other related functions.
-fno-operator-names
Do not treat the operator name keywords and, bitand, bitor, compl,
not, or and xor as synonyms as keywords.
-fno-optional-diags
Disable diagnostics that the standard says a compiler does not need to
issue. Currently, the only such diagnostic issued by G++ is the one
for a name having multiple meanings within a class.
-fpermissive
Downgrade messages about nonconformant code from errors to warnings.
By default, G++ effectively sets -pedantic-errors without -pedantic;
this option reverses that. This behavior and this option are
superseded by -pedantic, which works as it does for GNU C.
-frepo
Enable automatic template instantiation at link time. This option also
implies -fno-implicit-templates.
-fno-rtti
Disable generation of information about every class with virtual
functions for use by the C++ runtime type identification features
(dynamic_cast and typeid). If you don't use those parts of the
language, you can save some space by using this flag. Note that
exception handling uses the same information, but it will generate it
as needed.
-fstats
Emit statistics about front-end processing at the end of the
compilation. This information is generally only useful to the G++
development team.
-ftemplate-depth-n
Set the maximum instantiation depth for template classes to n. A limit
on the template instantiation depth is needed to detect endless
recursions during template class instantiation. ANSI/ISO C++
conforming programs must not rely on a maximum depth greater than 17.
-fuse-cxa-atexit
Register destructors for objects with static storage duration with the
__cxa_atexit function rather than the atexit function. This option is
required for fully standards-compliant handling of static destructors,
but will only work if your C library supports __cxa_atexit.
-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 -ffunction-
sections and -Wl,--gc-sections, in order to also discard the functions
themselves.
This optimization requires GNU as and GNU ld. Not all systems support
this option. -Wl,--gc-sections is ignored without -static.
-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++.
-nostdinC++
Do not search for header files in the standard directories specific to
C++, but do still search the other standard directories. (This option
is used when building the C++ library.)
In addition, these optimization, warning, and code generation options have
meanings only for C++programs:
-Wctor-dtor-privacy (C++ only)
Warn when a class seems unusable, because all the constructors or
destructors in a class are private and the class has no friends or
public static member functions. This warning is enabled by default.
-Wnon-virtual-dtor (C++ only)
Warn when a class declares a non-virtual destructor that should
probably be virtual, because it looks like the class will be used
polymorphically. This warning is enabled by -Wall.
-Wreorder (C++ only)
Warn when the order of member initializers given in the code does not
match the order in which they must be executed. For instance:
struct A {
int i;
int j;
A(): j (0), i (1) { }
};
Here the compiler will warn that the member initializers for i and j
will be rearranged to match the declaration order of the members. This
warning is enabled by -Wall.
The following -W... options are not affected by -Wall.
-WeffC++ (C++ only)
Warn about violations of the following style guidelines from Scott Meyers'
Effective C ++ book:
* Item 11: Define a copy constructor and an assignment operator for
classes with dynamically allocated memory.
* Item 12: Prefer initialization to assignment in constructors.
* Item 14: Make destructors virtual in base classes.
* Item 15: Have operator= return a reference to *this.
* Item 23: Don't try to return a reference when you must return an
object.
and about violations of the following style guidelines from Scott Meyers'
More Effective C ++ book:
* Item 6: Distinguish between prefix and postfix forms of increment
and decrement operators.
* Item 7: Never overload &&, ||, or ,.
If you use this option, you should be aware that the standard library
headers do not obey all of these guidelines; you can use grep -v to filter
out those warnings.
-Wno-deprecated (C++ only)
Do not warn about usage of deprecated features.
-Wno-non-template-friend (C++only)
Disable warnings when non-templatized friend functions are declared within
a template. With the advent of explicit template specification support in
G++, if the name of the friend is an unqualified-id (i.e., friend
foo(int)), the C++ language specification demands that the friend declare
or define an ordinary, nontemplate function. (Section 14.5.3). Before G++
implemented explicit specification, unqualified-ids could be interpreted
as a particular specialization of a templatized function. Because this
non-conforming behavior is no longer the default behavior for G++, -Wnon-
template-friend allows the compiler to check existing code for potential
trouble spots, and is on by default. This new compiler behavior can be
turned off with -Wno-non-template-friend which keeps the conformant
compiler code but disables the helpful warning.
-Wold-style-cast (C++ only)
Warn if an old-style (C-style) cast to a non-void type is used within a
C++ program. The new-style casts (static_cast, reinterpret_cast, and
const_cast) are less vulnerable to unintended effects, and much easier to
grep for.
-Woverloaded-virtual (C++ only)
Warn when a function declaration hides virtual functions from a base
class. For example, in:
struct A {
virtual void f();
};
struct B: public A {
void f(int);
};
the A class version of f is hidden in B, and code like this:
B* b;
b->f();
will fail to compile.
-Wno-pmf-conversions (C++ only)
Disable the diagnostic for converting a bound pointer to member function
to a plain pointer.
-Wsign-promo (C++ only)
Warn when overload resolution chooses a promotion from unsigned or
enumeral type to a signed type over a conversion to an unsigned type of
the same size. Previous versions of G++ would try to preserve
unsignedness, but the standard mandates the current behavior.
-Wsynth (C++ only)
Warn when G++'s synthesis behavior does not match that of cfront. For
instance:
struct A {
operator int ();
A& operator = (int);
};
main ()
{
A a,b;
a = b;
}
In this example, G++ will synthesize a default A& operator = (const A&);,
while cfront will use the user-defined operator =.
Options Controlling Objective-C Dialect
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 some_class.m like this:
gcc -g -fgnu-runtime -O -c some_class.m
In this example, only -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 only for compiling Objective-
C programs:
-fconstant-string-class=class-name
Use class-name as the name of the class to instantiate for each
literal string specified with the syntax @"...". The default class
name is NXConstantString.
-fgnu-runtime
Generate object code compatible with the standard GNU Objective-
C runtime. This is the default for most types of systems.
-fnext-runtime
Generate output compatible with the NeXT runtime. This is the default
for NeXT-based systems, including Darwin and Mac OS X. The macro
__NEXT_RUNTIME__ is predefined if (and only if) this option is used.
-gen-decls
Dump interface declarations for all classes seen in the source file to
a file named sourcename.decl.
-Wno-protocol
If a class is declared to implement a protocol, a warning is issued
for every method in the protocol that is not implemented by the class.
The default behavior is to issue a warning for every method not
explicitly implemented in the class, even if a method implementation
is inherited from the superclass. If you use the -Wno-protocol option,
then methods inherited from the superclass are considered to be
implemented, and no warning is issued for them.
-Wselector
Warn if multiple methods of different types for the same selector are
found during compilation. The check is performed on the list of
methods in the final stage of compilation. Additionally, a check is
performed that for each selector appearing in a @selector(...)
expression, a corresponding method with that selector has been found
during compilation. Because these checks scan the method table only at
the end of compilation, these warnings are not produced if the final
stage of compilation is not reached, for example because an error is
found during compilation, or because the -fsyntax-only option is being
used.
-Wundeclared-selector
Warn if a @selector(...) expression referring to an undeclared
selector is found. A selector is considered undeclared if no method
with that name has been declared (explicitly, in an @interface or
@protocol declaration, or implicitly, in an @implementation section)
before the @selector(...) expression. This option always performs its
checks as soon as a @selector(...) expression is found (while -
Wselector only performs its checks in the final stage of compilation),
and so additionally enforces the coding style convention that methods
and selectors must be declared before being used.
Options to Control Diagnostic Messages Formatting
Traditionally, diagnostic messages have been formatted irrespective of the
output device's aspect (e.g. its width,...). The options described below
can be used to control the diagnostic messages formatting algorithm, e.g.
how many characters per line, how often source location information should
be reported. Right now, only the C++ front end can honor these options.
However it is expected, in the near future, that the remaining front ends
would be able to digest them correctly.
-fmessage-length=n
Try to format error messages so that they fit on lines of about n
characters. The default is 72 characters for g++ and 0 for the rest of
the front ends supported by GCC. If n is zero, then no line-wrapping
will be done; each error message will appear on a single line.
-fdiagnostics-show-location=once
Only meaningful in line-wrapping mode. Instructs the diagnostic
messages reporter to emit once source location information; that is,
in case the message is too long to fit on a single physical line and
has to be wrapped, the source location won't be emitted (as prefix)
again, over and over, in subsequent continuation lines. This is the
default behavior.
-fdiagnostics-show-location=every-line
Only meaningful in line-wrapping mode. Instructs the diagnostic
messages reporter to emit the same source location information (as
prefix) for physical lines that result from the process of breaking a
message which is too long to fit on a single line.
Options to Request or Suppress Warnings
Warnings are diagnostic messages that report constructions which are not
inherently erroneous but which are risky or suggest there may have been an
error.
You can request many specific warnings with options beginning -W, for
example -Wimplicit to request warnings on implicit declarations. Each of
these specific warning options also has a negative form beginning -Wno- to
turn off warnings; for example, -Wno-implicit. This manual lists only one
of the two forms, whichever is not the default.
The following options control the amount and kinds of warnings produced by
GCC ; for further, language-specific options also refer to C++ Dialect
Options and Objective-C Dialect Options.
-fsyntax-only
Check the code for syntax errors, but don't do anything beyond that.
-pedantic
Issue all the warnings demanded by strict ISO C and ISO C++ ; reject
all programs that use forbidden extensions, and some other programs
that do not follow ISO C and ISO C++. For ISO C, follows the version
of the ISO C standard specified by any -std option used.
Valid ISO C and ISO C++ programs should compile properly with or without
this option (though a rare few will require -ansi or a -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.
-pedantic does not cause warning messages for use of the alternate
keywords whose names begin and end with __. Pedantic warnings are also
disabled in the expression that follows __extension__. However, only
system header files should use these escape routes; application programs
should avoid them.
Some users try to use -pedantic to check programs for strict ISO C
conformance. They soon find that it does not do quite what they want: it
finds some non-ISO practices, but not all---only those for which ISO C
requires a diagnostic, and some others for which diagnostics have been
added.
A feature to report any failure to conform to ISO C might be useful in
some instances, but would require considerable additional work and would
be quite different from -pedantic. We don't have plans to support such a
feature in the near future.
Where the standard specified with -std represents a GNU extended dialect
of C, such as gnu89 or gnu99, there is a corresponding base standard, the
version of ISO C on which the GNU extended dialect is based. Warnings from
-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.)
-pedantic-errors
Like -pedantic, except that errors are produced rather than warnings.
-w
Inhibit all warning messages.
-Wno-import
Inhibit warning messages about the use of #import.
-Wchar-subscripts
Warn if an array subscript has type char. This is a common cause of error,
as programmers often forget that this type is signed on some machines.
-Wcomment
Warn whenever a comment-start sequence /* appears in a /* comment, or
whenever a Backslash-Newline appears in a // comment.
-Wformat
Check calls to printf and scanf, etc., to make sure that the arguments
supplied have types appropriate to the format string specified, and that
the conversions specified in the format string make sense. This includes
standard functions, and others specified by format attributes, in the
printf, scanf, strftime and 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 C90 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 -pedantic is used with -
Wformat, warnings will be given about format features not in the selected
standard version (but not for strfmon formats, since those are not in any
version of the C standard).
Since -Wformat also checks for null format arguments for several
functions, -Wformat also implies -Wnonnull.
-Wformat is included in -Wall. For more control over some aspects of
format checking, the options -Wno-format-y2k, -Wno-format-extra-args, -
Wno-format-zero-length, -Wformat-nonliteral, -Wformat-security, and -
Wformat=2 are available, but are not included in -Wall.
-Wno-format-y2k
If -Wformat is specified, do not warn about strftime formats which may
yield only a two-digit year.
-Wno-format-extra-args
If -Wformat is specified, do not warn about excess arguments to a printf
or scanf format function. The C standard specifies that such arguments are
ignored.
Where the unused arguments lie between used arguments that are specified
with $ operand number specifications, normally warnings are still given,
since the implementation could not know what type to pass to va_arg to
skip the unused arguments. However, in the case of scanf formats, this
option will suppress the warning if the unused arguments are all pointers,
since the Single Unix Specification says that such unused arguments are
allowed.
-Wno-format-zero-length
If -Wformat is specified, do not warn about zero-length formats. The C
standard specifies that zero-length formats are allowed.
-Wformat-nonliteral
If -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 va_list.
-Wformat-security
If -Wformat is specified, also warn about uses of format functions that
represent possible security problems. At present, this warns about calls
to printf and scanf functions where the format string is not a string
literal and there are no format arguments, as in printf (foo);. This may
be a security hole if the format string came from untrusted input and
contains %n. (This is currently a subset of what -Wformat-nonliteral warns
about, but in future warnings may be added to -Wformat-security that are
not included in -Wformat-nonliteral.)
-Wformat=2
Enable -Wformat plus format checks not included in -Wformat. Currently
equivalent to -Wformat -Wformat-nonliteral -Wformat-security.
-Wnonnull
Enable warning about passing a null pointer for arguments marked as
requiring a non-null value by the nonnull function attribute.
-Wnonnull is included in -Wall and -Wformat. It can be disabled with the -
Wno-nonnull option.
-Wimplicit-int
Warn when a declaration does not specify a type.
-Wimplicit-function-declaration
-Werror-implicit-function-declaration
Give a warning (or error) whenever a function is used before being
declared.
-Wimplicit
Same as -Wimplicit-int and -Wimplicit-function-declaration.
-Wmain
Warn if the type of main is suspicious. main should be a function with
external linkage, returning int, taking either zero arguments, two, or
three arguments of appropriate types.
-Wmissing-braces
Warn if an aggregate or union initializer is not fully bracketed. In the
following example, the initializer for a is not fully bracketed, but that
for b is fully bracketed.
int a[2][2] = { 0, 1, 2, 3 };
int b[2][2] = { { 0, 1 }, { 2, 3 } };
-Wparentheses
Warn if parentheses are omitted in certain contexts, such as when there is
an assignment in a context where a truth value is expected, or when
operators are nested whose precedence people often get confused about.
Also warn about constructions where there may be confusion to which if
statement an else branch belongs. Here is an example of such a case:
{
if (a)
if (b)
foo ();
else
bar ();
}
In C, every else branch belongs to the innermost possible if statement,
which in this example is if (b). This is often not what the programmer
expected, as illustrated in the above example by indentation the
programmer chose. When there is the potential for this confusion, GCC will
issue a warning when this flag is specified. To eliminate the warning, add
explicit braces around the innermost if statement so there is no way the
else could belong to the enclosing if. The resulting code would look like
this:
{
if (a)
{
if (b)
foo ();
else
bar ();
}
}
-Wsequence-point
Warn about code that may have undefined semantics because of violations of
sequence point rules in the C standard.
The C standard defines the order in which expressions in a C program are
evaluated in terms of sequence points, which represent a partial ordering
between the execution of parts of the program: those executed before the
sequence point, and those executed after it. These occur after the
evaluation of a full expression (one which is not part of a larger
expression), after the evaluation of the first operand of a &&, ||, ? : or
, (comma) operator, before a function is called (but after the evaluation
of its arguments and the expression denoting the called function), and in
certain other places. Other than as expressed by the sequence point rules,
the order of evaluation of subexpressions of an expression is not
specified. All these rules describe only a partial order rather than a
total order, since, for example, if two functions are called within one
expression with no sequence point between them, the order in which the
functions are called is not specified. However, the standards committee
have ruled that function calls do not overlap.
It is not specified when between sequence points modifications to the
values of objects take effect. Programs whose behavior depends on this
have undefined behavior; the C standard specifies that "Between the
previous and next sequence point an object shall have its stored value
modified at most once by the evaluation of an expression. Furthermore, the
prior value shall be read only to determine the value to be stored." If a
program breaks these rules, the results on any particular implementation
are entirely unpredictable.
Examples of code with undefined behavior are a = a++;, a[n] = b[n++] and
a[i++] = i;. Some more complicated cases are not diagnosed by this option,
and it may give an occasional false positive result, but in general it has
been found fairly effective at detecting this sort of problem in programs.
The present implementation of this option only works for C programs. A
future implementation may also work for C++ programs.
The C standard is worded confusingly, therefore there is some debate over
the precise meaning of the sequence point rules in subtle cases. Links to
discussions of the problem, including proposed formal definitions, may be
found on our readings page, at http://gcc.gnu.org/readings.html.
-Wreturn-type
Warn whenever a function is defined with a return-type that defaults to
int. Also warn about any return statement with no return-value in a
function whose return-type is not void.
For C++, a function without return type always produces a diagnostic
message, even when -Wno-return-type is specified. The only exceptions are
main and functions defined in system headers.
-Wswitch
Warn whenever a switch statement has an index of enumeral type and lacks a
case for one or more of the named codes of that enumeration. (The presence
of a default label prevents this warning.) case labels outside the
enumeration range also provoke warnings when this option is used.
-Wswitch-default
Warn whenever a switch statement does not have a default case.
-Wswitch-enum
Warn whenever a switch statement has an index of enumeral type and lacks a
case for one or more of the named codes of that enumeration. case labels
outside the enumeration range also provoke warnings when this option is
used.
-Wtrigraphs
Warn if any trigraphs are encountered that might change the meaning of the
program (trigraphs within comments are not warned about).
-Wunused-function
Warn whenever a static function is declared but not defined or a non\-
inline static function is unused.
-Wunused-label
Warn whenever a label is declared but not used.
To suppress this warning use the unused attribute.
-Wunused-parameter
Warn whenever a function parameter is unused aside from its declaration.
To suppress this warning use the unused attribute.
-Wunused-variable
Warn whenever a local variable or non-constant static variable is unused
aside from its declaration.
To suppress this warning use the unused attribute.
-Wunused-value
Warn whenever a statement computes a result that is explicitly not used.
To suppress this warning cast the expression to void.
-Wunused
All the above -Wunused options combined.
In order to get a warning about an unused function parameter, you must
either specify -W -Wunused or separately specify -Wunused-parameter.
-Wuninitialized
Warn if an automatic variable is used without first being initialized or
if a variable may be clobbered by a setjmp call.
These warnings are possible only in optimizing compilation, because they
require data flow information that is computed only when optimizing. If
you don't specify -O, you simply won't get these warnings.
These warnings occur only for variables that are candidates for register
allocation. Therefore, they do not occur for a variable that is declared
volatile, or whose address is taken, or whose size is other than 1, 2, 4
or 8 bytes. Also, they do not occur for structures, unions or arrays, even
when they are in registers.
Note that there may be no warning about a variable that is used only to
compute a value that itself is never used, because such computations may
be deleted by data flow analysis before the warnings are printed.
These warnings are made optional because GCC is not smart enough to see
all the reasons why the code might be correct despite appearing to have an
error. Here is one example of how this can happen:
{
int x;
switch (y)
{
case 1: x = 1;
break;
case 2: x = 4;
break;
case 3: x = 5;
}
foo (x);
}
If the value of y is always 1, 2 or 3, then x is always initialized, but
GCC doesn't know this. Here is another common case:
{
int save_y;
if (change_y) save_y = y, y = new_y;
...
if (change_y) y = save_y;
}
This has no bug because save_y is used only if it is set.
This option also warns when a non-volatile automatic variable might be
changed by a call to longjmp. These warnings as well are possible only in
optimizing compilation.
The compiler sees only the calls to setjmp. It cannot know where longjmp
will be called; in fact, a signal handler could call it at any point in
the code. As a result, you may get a warning even when there is in fact no
problem because longjmp cannot in fact be called at the place which would
cause a problem.
Some spurious warnings can be avoided if you declare all the functions you
use that never return as noreturn.
-Wunknown-pragmas
Warn when a #pragma directive is encountered which is not understood by
GCC. If this command line option is used, warnings will even be issued for
unknown pragmas in system header files. This is not the case if the
warnings were only enabled by the -Wall command line option.
-Wstrict-aliasing
This option is only active when -fstrict-aliasing is active. It warns
about code which might break the strict aliasing rules that the compiler
is using for optimization. The warning does not catch all cases, but does
attempt to catch the more common pitfalls. It is included in -Wall.
-Wall
All of the above -W options combined. This enables all the warnings about
constructions that some users consider questionable, and that are easy to
avoid (or modify to prevent the warning), even in conjunction with macros.
This also enables some language-specific warnings described in C++ Dialect
Options and Objective-C Dialect Options.
The following -W... options are not implied by -Wall. Some of them warn
about constructions that users generally do not consider questionable, but
which occasionally you might wish to check for; others warn about
constructions that are necessary or hard to avoid in some cases, and there
is no simple way to modify the code to suppress the warning.
Options for Debugging Your Program or GCC
GCC has various special options that are used for debugging either your
program or GCC:
-g
Produce debugging information in the operating system's native format
(stabs, COFF, XCOFF, or DWARF ). GDB can work with this debugging
information.
On most systems that use stabs format, -g enables use of extra debugging
information that only GDB can use; this extra information makes debugging
work better in GDB but will probably make other debuggers crash or refuse
to read the program. If you want to control for certain whether to
generate the extra information, use -gstabs+, -gstabs, -gxcoff+, -gxcoff,
-gdwarf-1+, -gdwarf-1, or -gvms (see below).
Unlike most other C compilers, GCC allows you to use -g with -O. The
shortcuts taken by optimized code may occasionally produce surprising
results: some variables you declared may not exist at all; flow of control
may briefly move where you did not expect it; some statements may not be
executed because they compute constant results or their values were
already at hand; some statements may execute in different places because
they were moved out of loops.
Nevertheless it proves possible to debug optimized output. This makes it
reasonable to use the optimizer for programs that might have bugs.
The following options are useful when GCC is generated with the capability
for more than one debugging format.
address
Print the address of each node. Usually this is not meaningful as it
changes according to the environment and source file. Its primary use
is for tying up a dump file with a debug environment.
slim
Inhibit dumping of members of a scope or body of a function merely
because that scope has been reached. Only dump such items when they
are directly reachable by some other path.
all
Turn on all options.
The following tree dumps are possible:
original
Dump before any tree based optimization, to file.original.
optimized
Dump after all tree based optimization, to file.optimized.
inlined
Dump after function inlining, to file.inlined.
-fsched-verbose=n
On targets that use instruction scheduling, this option controls the
amount of debugging output the scheduler prints. This information is
written to standard error, unless -dS or -dR is specified, in which case
it is output to the usual dump listing file, .sched or .sched2
respectively. However for n greater than nine, the output is always
printed to standard error.
For n greater than zero, -fsched-verbose outputs the same information as -
dRS. For n greater than one, it also output basic block probabilities,
detailed ready list information and unit/insn info. For n greater than
two, it includes RTL at abort point, control-flow and regions info. And
for n over four, -fsched-verbose also includes dependence info.
-save-temps
Store the usual "temporary" intermediate files permanently; place them in
the current directory and name them based on the source file. Thus,
compiling foo.c with -c -save-temps would produce files foo.i and foo.s,
as well as foo.o. This creates a preprocessed foo.i output file even
though the compiler now normally uses an integrated preprocessor.
-time
Report the CPU time taken by each subprocess in the compilation sequence.
For C source files, this is the compiler proper and assembler (plus the
linker if linking is done). The output looks like this:
# cc1 0.12 0.01
# as 0.00 0.01
The first number on each line is the "user time," that is time spent
executing the program itself. The second number is "system time," time
spent executing operating system routines on behalf of the program. Both
numbers are in seconds.
-print-file-name=library
Print the full absolute name of the library file library that would be
used when linking---and don't do anything else. With this option, GCC does
not compile or link anything; it just prints the file name.
-print-multi-directory
Print the directory name corresponding to the multilib selected by any
other switches present in the command line. This directory is supposed to
exist in GCC_EXEC_PREFIX.
-print-multi-lib
Print the mapping from multilib directory names to compiler switches that
enable them. The directory name is separated from the switches by ;, and
each switch starts with an @} instead of the @samp{-, without spaces
between multiple switches. This is supposed to ease shell-processing.
-print-prog-name=program
Like -print-file-name, but searches for a program such as cpp.
-print-libgcc-file-name
Same as -print-file-name=libgcc.a.
This is useful when you use -nostdlib or -nodefaultlibs but you do want to
link with libgcc.a. You can do
gcc -nostdlib ... ‘gcc -print-libgcc-file-name‘
-print-search-dirs
Print the name of the configured installation directory and a list of
program and library directories gcc will search---and don't do anything
else.
This is useful when gcc prints the error message installation problem,
cannot exec cpp0: No such file or directory. To resolve this you either
need to put cpp0 and the other compiler components where gcc expects to
find them, or you can set the environment variable GCC_EXEC_PREFIX to the
directory where you installed them. Don't forget the trailing '/'.
-dumpmachine
Print the compiler's target machine (for example, i686-pc-linux-gnu)---and
don't do anything else.
-dumpversion
Print the compiler version (for example, 3.0)---and don't do anything
else.
-dumpspecs
Print the compiler's built-in specs---and don't do anything else. (This is
used when GCC itself is being built.)
Options That Control Optimization
These options control various sorts of optimizations.
Without any optimization option, the compiler's goal is to reduce the cost
of compilation and to make debugging produce the expected results.
Statements are independent: if you stop the program with a breakpoint
between statements, you can then assign a new value to any variable or
change the program counter to any other statement in the function and get
exactly the results you would expect from the source code.
Turning on optimization flags makes the compiler attempt to improve the
performance and/or code size at the expense of compilation time and
possibly the ability to debug the program.
Not all optimizations are controlled directly by a flag. Only
optimizations that have a flag are listed.
-O
-O1
Optimize. Optimizing compilation takes somewhat more time, and a lot
more memory for a large function.
With -O, the compiler tries to reduce code size and execution time,
without performing any optimizations that take a great deal of compilation
time.
-O turns on the following optimization flags: -fdefer-pop -fmerge-
constants -fthread-jumps -floop-optimize -fcrossjumping -fif-conversion -
fif-conversion2 -fdelayed-branch -fguess-branch-probability -fcprop-
registers
-O also turns on -fomit-frame-pointer on machines where doing so does not
interfere with debugging.
-O2
Optimize even more. GCC performs nearly all supported optimizations
that do not involve a space-speed tradeoff. The compiler does not
perform loop unrolling or function inlining when you specify -O2. As
compared to -O, this option increases both compilation time and the
performance of the generated code.
-O2 turns on all optimization flags specified by -O. It also turns on the
following optimization flags: -fforce-mem -foptimize-sibling-calls -
fstrength-reduce -fcse-follow-jumps -fcse-skip-blocks -frerun-cse-after-
loop -frerun-loop-opt -fgcse -fgcse-lm -fgcse-sm -fdelete-null-pointer-
checks -fexpensive-optimizations -fregmove -fschedule-insns -fschedule-
insns2 -fsched-interblock -fsched-spec -fcaller-saves -fpeephole2 -
freorder-blocks -freorder-functions -fstrict-aliasing -falign-functions -
falign-jumps -falign-loops -falign-labels
Please note the warning under -fgcse about invoking -O2 on programs that
use computed gotos.
-O3
Optimize yet more. -O3 turns on all optimizations specified by -O2 and
also turns on the -finline-functions and -frename-registers options.
-O0
Do not optimize. This is the default.
-Os
Optimize for size. -Os enables all -O2 optimizations that do not
typically increase code size. It also performs further optimizations
designed to reduce code size.
-Os disables the following optimization flags: -falign-functions -falign-
jumps -falign-loops -falign-labels -freorder-blocks -fprefetch-loop-arrays
If you use multiple -O options, with or without level numbers, the last
such option is the one that is effective.
Options of the form -fflag specify machine-independent flags. Most flags
have both positive and negative forms; the negative form of -ffoo would be
-fno-foo. In the table below, only one of the forms is listed---the one
you typically will use. You can figure out the other form by either
removing no- or adding it.
The following options control specific optimizations. They are either
activated by -O options or are related to ones that are. You can use the
following flags in the rare cases when "fine-tuning" of optimizations to
be performed is desired.
-fsignaling-nans
Compile code assuming that IEEE signaling NaNs may generate user-
visible traps during floating-point operations. Setting this option
disables optimizations that may change the number of exceptions
visible with signaling NaNs. This option implies -ftrapping-math.
This option causes the preprocessor macro __SUPPORT_SNAN__ to be
defined.
The default is -fno-signaling-nans.
This option is experimental and does not currently guarantee to
disable all GCC optimizations that affect signaling NaN behavior.
-fsingle-precision-constant
Treat floating point constant as single precision constant instead of
implicitly converting it to double precision constant.
The following options control optimizations that may improve performance,
but are not enabled by any -O options. This section includes experimental
options that may produce broken code.
-fbranch-probabilities
After running a program compiled with -fprofile-arcs, you can compile
it a second time using -fbranch-probabilities, to improve
optimizations based on the number of times each branch was taken. When
the program compiled with -fprofile-arcs exits it saves arc execution
counts to a file called sourcename.da for each source file The
information in this data file is very dependent on the structure of
the generated code, so you must use the same source code and the same
optimization options for both compilations.
With -fbranch-probabilities, GCC puts a REG_BR_PROB note on each
JUMP_INSN and CALL_INSN. These can be used to improve optimization.
Currently, they are only used in one place: in reorg.c, instead of
guessing which path a branch is mostly to take, the REG_BR_PROB values
are used to exactly determine which path is taken more often.
-fnew-ra
Use a graph coloring register allocator. Currently this option is
meant for testing, so we are interested to hear about miscompilations
with -fnew-ra.
-ftracer
Perform tail duplication to enlarge superblock size. This
transformation simplifies the control flow of the function allowing
other optimizations to do better job.
-funroll-loops
Unroll loops whose number of iterations can be determined at compile
time or upon entry to the loop. -funroll-loops implies both -
fstrength-reduce and -frerun-cse-after-loop. This option makes code
larger, and may or may not make it run faster.
-funroll-all-loops
Unroll all loops, even if their number of iterations is uncertain when
the loop is entered. This usually makes programs run more slowly. -
funroll-all-loops implies the same options as -funroll-loops,
-fprefetch-loop-arrays
If supported by the target machine, generate instructions to prefetch
memory to improve the performance of loops that access large arrays.
Disabled at level -Os.
-ffunction-sections
-fdata-sections
Place each function or data item into its own section in the output
file if the target supports arbitrary sections. The name of the
function or the name of the data item determines the section's name in
the output file.
Use these options on systems where the linker can perform
optimizations to improve locality of reference in the instruction
space. Most systems using the ELF object format and SPARC processors
running Solaris 2 have linkers with such optimizations. AIX may have
these optimizations in the future.
Only use these options when there are significant benefits from doing
so. When you specify these options, the assembler and linker will
create larger object and executable files and will also be slower. You
will not be able to use gprof on all systems if you specify this
option and you may have problems with debugging if you specify both
this option and -g.
-fssa
Perform optimizations in static single assignment form. Each
function's flow graph is translated into SSA form, optimizations are
performed, and the flow graph is translated back from SSA form. Users
should not specify this option, since it is not yet ready for
production use.
-fssa-ccp
Perform Sparse Conditional Constant Propagation in SSA form. Requires
-fssa. Like -fssa, this is an experimental feature.
-fssa-dce
Perform aggressive dead-code elimination in SSA form. Requires -fssa.
Like -fssa, this is an experimental feature.
--param name=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 --param
option.
In each case, the value is an integer. The allowable choices for name
are given in the following list:
max-crossjump-edges
The maximum number of incoming edges to consider for crossjumping.
The algorithm used by -fcrossjumping is O(N^2) in the number of
edges incoming to each block. Increasing values mean more
aggressive optimization, making the compile time increase with
probably small improvement in executable size.
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.
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.
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.
max-gcse-passes
The maximum number of passes of GCSE to run.
max-pending-list-length
The maximum number of pending dependencies scheduling will allow
before flushing the current state and starting over. Large
functions with few branches or calls can create excessively large
lists which needlessly consume memory and resources.
max-inline-insns-single
Several parameters control the tree inliner used in gcc. This
number sets the maximum number of instructions (counted in gcc's
internal representation) in a single function that the tree
inliner will consider for inlining. This only affects functions
declared inline and methods implemented in a class declaration
(C++ ). The default value is 300.
max-inline-insns-auto
When you use -finline-functions (included in -O3), a lot of
functions that would otherwise not be considered for inlining by
the compiler will be investigated. To those functions, a different
(more restrictive) limit compared to functions declared inline can
be applied. The default value is 300.
max-inline-insns
The tree inliner does decrease the allowable size for single
functions to be inlined after we already inlined the number of
instructions given here by repeated inlining. This number should
be a factor of two or more larger than the single function limit.
Higher numbers result in better runtime performance, but incur
higher compile-time resource (CPU time, memory) requirements and
result in larger binaries. Very high values are not advisable, as
too large binaries may adversely affect runtime performance. The
default value is 600.
max-inline-slope
After exceeding the maximum number of inlined instructions by
repeated inlining, a linear function is used to decrease the
allowable size for single functions. The slope of that function is
the negative reciprocal of the number specified here. The default
value is 32.
min-inline-insns
The repeated inlining is throttled more and more by the linear
function after exceeding the limit. To avoid too much throttling,
a minimum for this function is specified here to allow repeated
inlining for very small functions even when a lot of repeated
inlining already has been done. The default value is 130.
max-inline-insns-rtl
For languages that use the RTL inliner (this happens at a later
stage than tree inlining), you can set the maximum allowable size
(counted in RTL instructions) for the RTL inliner with this
parameter. The default value is 600.
max-unrolled-insns
The maximum number of instructions that a loop should have if that
loop is unrolled, and if the loop is unrolled, it determines how
many times the loop code is unrolled.
hot-bb-count-fraction
Select fraction of the maximal count of repetitions of basic block
in program given basic block needs to have to be considered hot.
hot-bb-frequency-fraction
Select fraction of the maximal frequency of executions of basic
block in function given basic block needs to have to be considered
hot
tracer-dynamic-coverage
tracer-dynamic-coverage-feedback
This value is used to limit superblock formation once the given
percentage of executed instructions is covered. This limits
unnecessary code size expansion.
The tracer-dynamic-coverage-feedback is used only when profile
feedback is available. The real profiles (as opposed to statically
estimated ones) are much less balanced allowing the threshold to
be larger value.
tracer-max-code-growth
Stop tail duplication once code growth has reached given
percentage. This is rather hokey argument, as most of the
duplicates will be eliminated later in cross jumping, so it may be
set to much higher values than is the desired code growth.
tracer-min-branch-ratio
Stop reverse growth when the reverse probability of best edge is
less than this threshold (in percent).
tracer-min-branch-ratio
tracer-min-branch-ratio-feedback
Stop forward growth if the best edge do have probability lower
than this threshold.
Similarly to tracer-dynamic-coverage two values are present, one
for compilation for profile feedback and one for compilation
without. The value for compilation with profile feedback needs to
be more conservative (higher) in order to make tracer effective.
ggc-min-expand
GCC uses a garbage collector to manage its own memory allocation.
This parameter specifies the minimum percentage by which the
garbage collector's heap should be allowed to expand between
collections. Tuning this may improve compilation speed; it has no
effect on code generation.
The default is 30% + 70% * ( RAM/1GB ) with an upper bound of 100%
when RAM >= 1GB. If getrlimit is available, the notion of " RAM "
is the smallest of actual RAM, RLIMIT_RSS, RLIMIT_DATA and
RLIMIT_AS. If GCC is not able to calculate RAM on a particular
platform, the lower bound of 30% is used. Setting this parameter
and ggc-min-heapsize to zero causes a full collection to occur at
every opportunity. This is extremely slow, but can be useful for
debugging.
ggc-min-heapsize
Minimum size of the garbage collector's heap before it begins
bothering to collect garbage. The first collection occurs after
the heap expands by ggc-min-expand% beyond ggc-min-heapsize.
Again, tuning this may improve compilation speed, and has no
effect on code generation.
The default is RAM/8, with a lower bound of 4096 (four megabytes)
and an upper bound of 131072 (128 megabytes). If getrlimit is
available, the notion of " RAM " is the smallest of actual RAM,
RLIMIT_RSS, RLIMIT_DATA and RLIMIT_AS. If GCC is not able to
calculate RAM on a particular platform, the lower bound is used.
Setting this parameter very large effectively disables garbage
collection. Setting this parameter and ggc-min-expand to zero
causes a full collection to occur at every opportunity.
Options Controlling the Preprocessor
These options control the C preprocessor, which is run on each C source
file before actual compilation.
If you use the -E option, nothing is done except preprocessing. Some of
these options make sense only together with -E because they cause the
preprocessor output to be unsuitable for actual compilation.
You can use -Wp,option to bypass the compiler driver and pass option
directly through to the preprocessor. If option contains commas, it is
split into multiple options at the commas. However, many options are
modified, translated or interpreted by the compiler driver before being
passed to the preprocessor, and -Wp forcibly bypasses this phase. The
preprocessor's direct interface is undocumented and subject to change, so
whenever possible you should avoid using -Wp and let the driver handle the
options instead.
-D name
Predefine name as a macro, with definition 1.
-D name=definition
Predefine name as a macro, with definition definition. There are no
restrictions on the contents of definition, but if you are invoking
the preprocessor from a shell or shell-like program you may need to
use the shell's quoting syntax to protect characters such as spaces
that have a meaning in the shell syntax.
If you wish to define a function-like macro on the command line, write its
argument list with surrounding parentheses before the equals sign (if
any). Parentheses are meaningful to most shells, so you will need to quote
the option. With sh and csh, -D'name(args...)=definition' works.
-D and -U options are processed in the order they are given on the command
line. All -imacros file and -include file options are processed after all
-D and -U options.
-U name
Cancel any previous definition of name, either built in or provided with a
-D option.
-undef
Do not predefine any system-specific macros. The common predefined macros
remain defined.
-I dir
Add the directory dir to the list of directories to be searched for header
files. Directories named by -I are searched before the standard system
include directories. If the directory dir is a standard system include
directory, the option is ignored to ensure that the default search order
for system directories and the special treatment of system headers are not
defeated.
-o file
Write output to file. This is the same as specifying file as the second
non-option argument to cpp. gcc has a different interpretation of a second
non-option argument, so you must use -o to specify the output file.
-Wall
Turns on all optional warnings which are desirable for normal code. At
present this is -Wcomment and -Wtrigraphs. Note that many of the
preprocessor's warnings are on by default and have no options to control
them.
-Wcomment
-Wcomments
Warn whenever a comment-start sequence /* appears in a /* comment, or
whenever a backslash-newline appears in a // comment. (Both forms have the
same effect.)
-Wtrigraphs
Warn if any trigraphs are encountered. This option used to take effect
only if -trigraphs was also specified, but now works independently.
Warnings are not given for trigraphs within comments, as they do not
affect the meaning of the program.
-Wtraditional
Warn about certain constructs that behave differently in traditional and
ISO C. Also warn about ISO C constructs that have no traditional C
equivalent, and problematic constructs which should be avoided.
-Wimport
Warn the first time #import is used.
-Wundef
Warn whenever an identifier which is not a macro is encountered in an #if
directive, outside of defined. Such identifiers are replaced with zero.
-Wunused-macros
Warn about macros defined in the main file that are unused. A macro is
used if it is expanded or tested for existence at least once. The
preprocessor will also warn if the macro has not been used at the time it
is redefined or undefined.
Built-in macros, macros defined on the command line, and macros defined in
include files are not warned about.
Note: If a macro is actually used, but only used in skipped conditional
blocks, then CPP will report it as unused. To avoid the warning in such a
case, you might improve the scope of the macro's definition by, for
example, moving it into the first skipped block. Alternatively, you could
provide a dummy use with something like:
#if defined the_macro_causing_the_warning
#endif
-Wendif-labels
Warn whenever an #else or an #endif are followed by text. This usually
happens in code of the form
#if FOO
...
#else FOO
...
#endif FOO
The second and third FOO should be in comments, but often are not in older
programs. This warning is on by default.
-Werror
Make all warnings into hard errors. Source code which triggers warnings
will be rejected.
-Wsystem-headers
Issue warnings for code in system headers. These are normally unhelpful in
finding bugs in your own code, therefore suppressed. If you are
responsible for the system library, you may want to see them.
-w
Suppress all warnings, including those which GNU CPP issues by default.
-pedantic
Issue all the mandatory diagnostics listed in the C standard. Some of them
are left out by default, since they trigger frequently on harmless code.
-pedantic-errors
Issue all the mandatory diagnostics, and make all mandatory diagnostics
into errors. This includes mandatory diagnostics that GCC issues without -
pedantic but treats as warnings.
-M
Instead of outputting the result of preprocessing, output a rule suitable
for make describing the dependencies of the main source file. The
preprocessor outputs one make rule containing the object file name for
that source file, a colon, and the names of all the included files,
including those coming from -include or -imacros command line options.
Unless specified explicitly (with -MT or -MQ), 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 \-newline. The rule has no commands.
This option does not suppress the preprocessor's debug output, such as -
dM. To avoid mixing such debug output with the dependency rules you should
explicitly specify the dependency output file with -MF, or use an
environment variable like DEPENDENCIES_OUTPUT. Debug output will still be
sent to the regular output stream as normal.
Passing -M to the driver implies -E, and suppresses warnings with an
implicit -w.
-MM
Like -M but do not mention header files that are found in system header
directories, nor header files that are included, directly or indirectly,
from such a header.
This implies that the choice of angle brackets or double quotes in an
#include directive does not in itself determine whether that header will
appear in -MM dependency output. This is a slight change in semantics from
GCC versions 3.0 and earlier.
-MF file
When used with -M or -MM, specifies a file to write the dependencies to.
If no -MF switch is given the preprocessor sends the rules to the same
place it would have sent preprocessed output.
When used with the driver options -MD or -MMD, -MF overrides the default
dependency output file.
-MG
In conjunction with an option such as -M requesting dependency generation,
-MG assumes missing header files are generated files and adds them to the
dependency list without raising an error. The dependency filename is taken
directly from the #include directive without prepending any path. -MG also
suppresses preprocessed output, as a missing header file renders this
useless.
This feature is used in automatic updating of makefiles.
-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 make gives if you remove header files without updating
the Makefile to match.
This is typical output:
test.o: test.c test.h
test.h:
-MT target
Change the target of the rule emitted by dependency generation. By default
CPP takes the name of the main input file, including any path, deletes any
file suffix such as .c, and appends the platform's usual object suffix.
The result is the target.
An -MT option will set the target to be exactly the string you specify. If
you want multiple targets, you can specify them as a single argument to -
MT, or use multiple -MT options.
For example, -MT '$(objpfx)foo.o' might give
$(objpfx)foo.o: foo.c
-MQ target
Same as -MT, but it quotes any characters which are special to Make. -MQ
'$(objpfx)foo.o' gives
$$(objpfx)foo.o: foo.c
The default target is automatically quoted, as if it were given with -MQ.
-MD
-MD is equivalent to -M -MF file, except that -E is not implied. The
driver determines file based on whether an -o option is given. If it is,
the driver uses its argument but with a suffix of .d, otherwise it take
the basename of the input file and applies a .d suffix.
If -MD is used in conjunction with -E, any -o switch is understood to
specify the dependency output file (but @pxref{-MF}), but if used without
-E, each -o is understood to specify a target object file.
Since -E is not implied, -MD can be used to generate a dependency output
file as a side-effect of the compilation process.
-MMD
Like -MD except mention only user header files, not system -header files.
-x c
-x C++
-x objective-c
-x assembler-with-cpp
Specify the source language: C, C++, Objective-C, or assembly. This has
nothing to do with standards conformance or extensions; it merely selects
which base syntax to expect. If you give none of these options, cpp will
deduce the language from the extension of the source file: .c, .cc, .m, or
.S. Some other common extensions for C++ and assembly are also recognized.
If cpp does not recognize the extension, it will treat the file as C; this
is the most generic mode.
Note: Previous versions of cpp accepted a -lang option which selected both
the language and the standards conformance level. This option has been
removed, because it conflicts with the -l option.
-std=standard
-ansi
Specify the standard to which the code should conform. Currently CPP knows
about C and C++ standards; others may be added in the future.
standard may be one of:
iso9899:1990
c89
The ISO C standard from 1990. c89 is the customary shorthand for this
version of the standard.
The -ansi option is equivalent to -std=c89.
iso9899:199409
The 1990 C standard, as amended in 1994.
iso9899:1999
c99
iso9899:199x
c9x
The revised ISO C standard, published in December 1999. Before
publication, this was known as C9X.
gnu89
The 1990 C standard plus GNU extensions. This is the default.
gnu99
gnu9x
The 1999 C standard plus GNU extensions.
C++ 98
The 1998 ISO C++ standard plus amendments.
gnu++98
The same as -std=C++ 98 plus GNU extensions. This is the default for
C++ code.
-I-
Split the include path. Any directories specified with -I options before -
I- are searched only for headers requested with #include "file"; they are
not searched for #include . If additional directories are specified
with -I options after the -I-, those directories are searched for all
#include directives.
In addition, -I- inhibits the use of the directory of the current file
directory as the first search directory for #include "file".
-nostdinc
Do not search the standard system directories for header files. Only the
directories you have specified with -I options (and the directory of the
current file, if appropriate) are searched.
-nostdinC++
Do not search for header files in the C++ -specific standard directories,
but do still search the other standard directories. (This option is used
when building the C++ library.)
-include file
Process file as if #include "file" appeared as the first line of the
primary source file. However, the first directory searched for file is the
preprocessor's working directory instead of the directory containing the
main source file. If not found there, it is searched for in the remainder
of the #include "..." search chain as normal.
If multiple -include options are given, the files are included in the
order they appear on the command line.
-imacros file
Exactly like -include, except that any output produced by scanning file is
thrown away. Macros it defines remain defined. This allows you to acquire
all the macros from a header without also processing its declarations.
All files specified by -imacros are processed before all files specified
by -include.
-idirafter dir
Search dir for header files, but do it after all directories specified
with -I and the standard system directories have been exhausted. dir is
treated as a system include directory.
-iprefix prefix
Specify prefix as the prefix for subsequent -iwithprefix options. If the
prefix represents a directory, you should include the final /.
-iwithprefix dir
-iwithprefixbefore dir
Append dir to the prefix specified previously with -iprefix, and add the
resulting directory to the include search path. -iwithprefixbefore puts it
in the same place -I would; -iwithprefix puts it where -idirafter would.
Use of these options is discouraged.
-isystem dir
Search dir for header files, after all directories specified by -I but
before the standard system directories. Mark it as a system directory, so
that it gets the same special treatment as is applied to the standard
system directories.
-fpreprocessed
Indicate to the preprocessor that the input file has already been
preprocessed. This suppresses things like macro expansion, trigraph
conversion, escaped newline splicing, and processing of most directives.
The preprocessor still recognizes and removes comments, so that you can
pass a file preprocessed with -C to the compiler without problems. In this
mode the integrated preprocessor is little more than a tokenizer for the
front ends.
-fpreprocessed is implicit if the input file has one of the extensions .i,
.ii or .mi. These are the extensions that GCC uses for preprocessed files
created by -save-temps.
-ftabstop=width
Set the distance between tab stops. This helps the preprocessor report
correct column numbers in warnings or errors, even if tabs appear on the
line. If the value is less than 1 or greater than 100, the option is
ignored. The default is 8.
-fno-show-column
Do not print column numbers in diagnostics. This may be necessary if
diagnostics are being scanned by a program that does not understand the
column numbers, such as dejagnu.
-A predicate=answer
Make an assertion with the predicate predicate and answer answer. This
form is preferred to the older form -A predicate(answer), which is still
supported, because it does not use shell special characters.
-A -predicate=answer
Cancel an assertion with the predicate predicate and answer answer.
-dCHARS
CHARS is a sequence of one or more of the following characters, and must
not be preceded by a space. Other characters are interpreted by the
compiler proper, or reserved for future versions of GCC, and so are
silently ignored. If you specify characters whose behavior conflicts, the
result is undefined.
M
Instead of the normal output, generate a list of #define directives
for all the macros defined during the execution of the preprocessor,
including predefined macros. This gives you a way of finding out what
is predefined in your version of the preprocessor. Assuming you have
no file foo.h, the command
touch foo.h; cpp -dM foo.h
will show all the predefined macros.
D
Like M except in two respects: it does not include the predefined
macros, and it outputs both the #define directives and the result of
preprocessing. Both kinds of output go to the standard output file.
N
Like D, but emit only the macro names, not their expansions.
I
Output #include directives in addition to the result of preprocessing.
-P
Inhibit generation of linemarkers in the output from the preprocessor.
This might be useful when running the preprocessor on something that is
not C code, and will be sent to a program which might be confused by the
linemarkers.
-C
Do not discard comments. All comments are passed through to the output
file, except for comments in processed directives, which are deleted along
with the directive.
You should be prepared for side effects when using -C; it causes the
preprocessor to treat comments as tokens in their own right. For example,
comments appearing at the start of what would be a directive line have the
effect of turning that line into an ordinary source line, since the first
token on the line is no longer a #.
-CC
Do not discard comments, including during macro expansion. This is like -
C, except that comments contained within macros are also passed through to
the output file where the macro is expanded.
In addition to the side-effects of the -C option, the -CC option causes
all C++ -style comments inside a macro to be converted to C-style
comments. This is to prevent later use of that macro from inadvertently
commenting out the remainder of the source line.
The -CC option is generally used to support lint comments.
-gcc
Define the macros __GNUC__, __GNUC_MINOR__ and __GNUC_PATCHLEVEL__. These
are defined automatically when you use gcc -E; you can turn them off in
that case with -no-gcc.
-traditional-cpp
Try to imitate the behavior of old-fashioned C preprocessors, as opposed
to ISO C preprocessors.
-trigraphs
Process trigraph sequences. These are three-character sequences, all
starting with ??, that are defined by ISO C to stand for single
characters. For example, ??/ stands for \, so '??/n' is a character
constant for a newline. By default, GCC ignores trigraphs, but in
standard-conforming modes it converts them. See the -std and -ansi
options.
The nine trigraphs and their replacements are
Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??-
Replacement: [ ] { } # \ ^ | ~
-remap
Enable special code to work around file systems that only permit very
short file names, such as MS-DOS.
--help
--target-help
Print text describing all the command line options instead of
preprocessing anything.
-v
Verbose mode. Print out GNU CPP's version number at the beginning of
execution, and report the final form of the include path.
-H
Print the name of each header file used, in addition to other normal
activities. Each name is indented to show how deep in the #include stack
it is.
-version
--version
Print out GNU CPP's version number. With one dash, proceed to preprocess
as normal. With two dashes, exit immediately.
Passing Options to the Assembler
You can pass options to the assembler.
-Wa,option
Pass option as an option to the assembler. If option contains commas,
it is split into multiple options at the commas.
Options for Linking
These options come into play when the compiler links object files into an
executable output file. They are meaningless if the compiler is not doing
a link step.
object-file-name
A file name that does not end in a special recognized suffix is
considered to name an object file or library. (Object files are
distinguished from libraries by the linker according to the file
contents.) If linking is done, these object files are used as input to
the linker.
-c
-S
-E
If any of these options is used, then the linker is not run, and
object file names should not be used as arguments.
-llibrary
-l library
Search the library named library when linking. (The second alternative
with the library as a separate argument is only for POSIX compliance
and is not recommended.)
It makes a difference where in the command you write this option; the
linker searches and processes libraries and object files in the order
they are specified. Thus, foo.o -lz bar.o searches library z after
file foo.o but before bar.o. If bar.o refers to functions in z, those
functions may not be loaded.
The linker searches a standard list of directories for the library,
which is actually a file named liblibrary.a. The linker then uses this
file as if it had been specified precisely by name.
The directories searched include several standard system directories
plus any that you specify with -L.
Normally the files found this way are library files---archive files
whose members are object files. The linker handles an archive file by
scanning through it for members which define symbols that have so far
been referenced but not defined. But if the file that is found is an
ordinary object file, it is linked in the usual fashion. The only
difference between using an -l option and specifying a file name is
that -l surrounds library with lib and .a and searches several
directories.
-lobjc
You need this special case of the -l option in order to link an
Objective-C program.
-nostartfiles
Do not use the standard system startup files when linking. The
standard system libraries are used normally, unless -nostdlib or -
nodefaultlibs is used.
-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 -nostartfiles is used. The
compiler may generate calls to memcmp, memset, and memcpy for System V
(and ISO C) environments or to bcopy and bzero for BSD environments.
These entries are usually resolved by entries in libc. These entry
points should be supplied through some other mechanism when this
option is specified.
-nostdlib
Do not use the standard system startup files or libraries when
linking. No startup files and only the libraries you specify will be
passed to the linker. The compiler may generate calls to memcmp,
memset, and memcpy for System V (and ISO C) environments or to bcopy
and bzero for BSD environments. These entries are usually resolved by
entries in libc. These entry points should be supplied through some
other mechanism when this option is specified.
One of the standard libraries bypassed by -nostdlib and -nodefaultlibs
is libgcc.a, a library of internal subroutines that GCC uses to
overcome shortcomings of particular machines, or special needs for
some languages.
In most cases, you need libgcc.a even when you want to avoid other
standard libraries. In other words, when you specify -nostdlib or -
nodefaultlibs you should usually specify -lgcc as well. This ensures
that you have no unresolved references to internal GCC library
subroutines. (For example, __main, used to ensure C++ constructors
will be called.)
-s
Remove all symbol table and relocation information from the
executable.
-static
On systems that support dynamic linking, this prevents linking with
the shared libraries. On other systems, this option has no effect.
-shared
Produce a shared object which can then be linked with other objects to
form an executable. Not all systems support this option. For
predictable results, you must also specify the same set of options
that were used to generate code (-fpic, -fPIC, or model suboptions)
when you specify this option.[1]
-shared-libgcc
-static-libgcc
On systems that provide libgcc as a shared library, these options
force the use of either the shared or static version respectively. If
no shared version of 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 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 libgcc.
Therefore, the G++ and GCJ drivers automatically add -shared-libgcc
whenever you build a shared library or a main executable, because C++
and Java programs typically use exceptions, so this is the right thing
to do.
If, instead, you use the GCC driver to create shared libraries, you
may find that they will not always be linked with the shared libgcc.
If GCC finds, at its configuration time, that you have a GNU linker
that does not support option --eh-frame-hdr, it will link the shared
version of libgcc into shared libraries by default. Otherwise, it will
take advantage of the linker and optimize away the linking with the
shared version of libgcc, linking with the static version of libgcc by
default. This allows exceptions to propagate through such shared
libraries, without incurring relocation costs at library load time.
However, if a library or main executable is supposed to throw or catch
exceptions, you must link it using the G++ or GCJ driver, as
appropriate for the languages used in the program, or using the option
-shared-libgcc, such that it is linked with the shared libgcc.
-symbolic
Bind references to global symbols when building a shared object. Warn
about any unresolved references (unless overridden by the link editor
option -Xlinker -z -Xlinker defs). Only a few systems support this
option.
-Xlinker option
Pass option as an option to the linker. You can use this to supply
system-specific linker options which GCC does not know how to
recognize.
If you want to pass an option that takes an argument, you must use -
Xlinker twice, once for the option and once for the argument. For
example, to pass -assert definitions, you must write -Xlinker -assert
-Xlinker definitions. It does not work to write -Xlinker "-assert
definitions", because this passes the entire string as a single
argument, which is not what the linker expects.
-Wl,option
Pass option as an option to the linker. If option contains commas, it
is split into multiple options at the commas.
-u symbol
Pretend the symbol symbol is undefined, to force linking of library
modules to define it. You can use -u multiple times with different
symbols to force loading of additional library modules.
Options for Directory Search
These options specify directories to search for header files, for
libraries and for parts of the compiler:
-Idir
Add the directory dir to the head of the list of directories to be
searched for header files. This can be used to override a system
header file, substituting your own version, since these directories
are searched before the system header file directories. However, you
should not use this option to add directories that contain vendor-
supplied system header files (use -isystem for that). If you use more
than one -I option, the directories are scanned in left-to-right
order; the standard system directories come after.
If a standard system include directory, or a directory specified with
-isystem, is also specified with -I, the -I option will be ignored.
The directory will still be searched but as a system directory at its
normal position in the system include chain. This is to ensure that
GCC's procedure to fix buggy system headers and the ordering for the
include_next directive are not inadvertently changed. If you really
need to change the search order for system directories, use the -
nostdinc and/or -isystem options.
-I-
Any directories you specify with -I options before the -I- option are
searched only for the case of #include "file"; they are not searched
for #include .
If additional directories are specified with -I options after the -I-
, these directories are searched for all #include directives.
(Ordinarily all -I directories are used this way.)
In addition, the -I- option inhibits the use of the current directory
(where the current input file came from) as the first search directory
for #include "file". There is no way to override this effect of -I-
. With -I. you can specify searching the directory which was current
when the compiler was invoked. That is not exactly the same as what
the preprocessor does by default, but it is often satisfactory.
-I- does not inhibit the use of the standard system directories for
header files. Thus, -I- and -nostdinc are independent.
-Ldir
Add directory dir to the list of directories to be searched for -l.
-Bprefix
This option specifies where to find the executables, libraries,
include files, and data files of the compiler itself.
The compiler driver program runs one or more of the subprograms cpp,
cc1, as and ld. It tries prefix as a prefix for each program it tries
to run, both with and without machine/version/.
For each subprogram to be run, the compiler driver first tries the -
B prefix, if any. If that name is not found, or if -B was not
specified, the driver tries two standard prefixes, which are /usr/lib/
gcc/ and /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 PATH environment variable.
The compiler will check to see if the path provided by the -B refers
to a directory, and if necessary it will add a directory separator
character at the end of the path.
-B prefixes that effectively specify directory names also apply to
libraries in the linker, because the compiler translates these options
into -L options for the linker. They also apply to includes files in
the preprocessor, because the compiler translates these options into -
isystem options for the preprocessor. In this case, the compiler
appends include to the prefix.
The run-time support file libgcc.a can also be searched for using the
-B prefix, if needed. If it is not found there, the two standard
prefixes above are tried, and that is all. The file is left out of the
link if it is not found by those means.
Another way to specify a prefix much like the -B prefix is to use the
environment variable GCC_EXEC_PREFIX.
As a special kludge, if the path provided by -B is [dir/]stageN/
, where N is a number in the range 0 to 9, then it will be replaced by
[dir/]include. This is to help with boot-strapping the compiler.
-specs=file
Process file after the compiler reads in the standard specs file, in
order to override the defaults that the gcc driver program uses when
determining what switches to pass to cc1, cc1plus, as, ld, etc. More
than one -specs=file can be specified on the command line, and they
are processed in order, from left to right.
Specifying Target Machine and Compiler Version
The usual way to run GCC is to run the executable called gcc, or
-gcc when cross-compiling, or -gcc- to run a
version other than the one that was installed last. Sometimes this is
inconvenient, so GCC provides options that will switch to another cross-
compiler or version.
-b machine
The argument machine specifies the target machine for compilation.
The value to use for machine is the same as was specified as the
machine type when configuring GCC as a cross-compiler. For example, if
a cross-compiler was configured with configure i386v, meaning to
compile for an 80386 running System V, then you would specify -b i386v
to run that cross compiler.
-V version
The argument version specifies which version of GCC to run. This is
useful when multiple versions are installed. For example, version
might be 2.0, meaning to run GCC version 2.0.
The -V and -b options work by running the -gcc-
executable, so there's no real reason to use them if you can just run that
directly.
Hardware Models and Configurations
Earlier we discussed the standard option -b which chooses among different
installed compilers for completely different target machines, such as VAX
vs. 68000 vs. 80386.
In addition, each of these target machine types can have its own special
options, starting with -m, to choose among various hardware models or
configurations---for example, 68010 vs 68020, floating coprocessor or
none. A single installed version of the compiler can compile for any model
or configuration, according to the options specified.
Some configurations of the compiler also support additional special
options, usually for compatibility with other compilers on the same
platform.
These options are defined by the macro TARGET_SWITCHES in the machine
description. The default for the options is also defined by that macro,
which enables you to change the defaults.
Intel 386 and AMD x86-64 Options
These -m options are defined for the i386 and x86-64 family of computers:
sse
Use scalar floating point instructions present in the SSE instruction
set. This instruction set is supported by Pentium3 and newer chips, in
the AMD line by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier
version of SSE instruction set supports only single precision
arithmetics, thus the double and extended precision arithmetics is
still done using 387. Later version, present only in Pentium4 and the
future AMD x86-64 chips supports double precision arithmetics too.
For i387 you need to use -march=cpu-type, -msse or -msse2 switches to
enable SSE extensions and make this option effective. For x86-64
compiler, these extensions are enabled by default.
The resulting code should be considerably faster in majority of cases
and avoid the numerical instability problems of 387 code, but may
break some existing code that expects temporaries to be 80bit.
This is the default choice for x86-64 compiler.
sse,387
Attempt to utilize both instruction sets at once. This effectively
double the amount of available registers and on chips with separate
execution units for 387 and SSE the execution resources too. Use this
option with care, as it is still experimental, because gcc register
allocator does not model separate functional units well resulting in
instable performance.
-masm=dialect
Output asm instructions using selected dialect. Supported choices are
intel or att (the default one).
-mieee-fp
-mno-ieee-fp
Control whether or not the compiler uses IEEE floating point comparisons.
These handle correctly the case where the result of a comparison is
unordered.
-msoft-float
Generate output containing library calls for floating point. Warning: the
requisite libraries are not part of GCC. Normally the facilities of the
machine's usual C compiler are used, but this can't be done directly in
cross-compilation. You must make your own arrangements to provide suitable
library functions for cross-compilation.
On machines where a function returns floating point results in the 80387
register stack, some floating point opcodes may be emitted even if -msoft-
float is used.
-mno-fp-ret-in-387
Do not use the FPU registers for return values of functions.
The usual calling convention has functions return values of types float
and double in an FPU register, even if there is no FPU. The idea is that
the operating system should emulate an FPU.
The option -mno-fp-ret-in-387 causes such values to be returned in
ordinary CPU registers instead.
-mno-fancy-math-387
Some 387 emulators do not support the sin, cos and sqrt instructions for
the 387. Specify this option to avoid generating those instructions. This
option is the default on FreeBSD, OpenBSD and NetBSD. This option is
overridden when -march indicates that the target cpu will always have an
FPU and so the instruction will not need emulation. As of revision 2.6.1,
these instructions are not generated unless you also use the -funsafe-
math-optimizations switch.
-malign-double
-mno-align-double
Control whether GCC aligns double, long double, and long long variables on
a two word boundary or a one word boundary. Aligning double variables on a
two word boundary will produce code that runs somewhat faster on a Pentium
at the expense of more memory.
Warning: if you use the -malign-double switch, structures containing the
above types will be aligned differently than the published application
binary interface specifications for the 386 and will not be binary
compatible with structures in code compiled without that switch.
-m128bit-long-double
Control the size of long double type. i386 application binary interface
specify the size to be 12 bytes, while modern architectures (Pentium and
newer) prefer long double aligned to 8 or 16 byte boundary. This is
impossible to reach with 12 byte long doubles in the array accesses.
Warning: if you use the -m128bit-long-double switch, the structures and
arrays containing long double will change their size as well as function
calling convention for function taking long double will be modified.
-m96bit-long-double
Set the size of long double to 96 bits as required by the i386 application
binary interface. This is the default.
-msvr3-shlib
-mno-svr3-shlib
Control whether GCC places uninitialized local variables into the bss or
data segments. -msvr3-shlib places them into bss. These options are
meaningful only on System V Release 3.
-mrtd
Use a different function-calling convention, in which functions that take
a fixed number of arguments return with the ret num instruction, which
pops their arguments while returning. This saves one instruction in the
caller since there is no need to pop the arguments there.
You can specify that an individual function is called with this calling
sequence with the function attribute stdcall. You can also override the -
mrtd option by using the function attribute cdecl.
Warning: this calling convention is incompatible with the one normally
used on Unix, so you cannot use it if you need to call libraries compiled
with the Unix compiler.
Also, you must provide function prototypes for all functions that take
variable numbers of arguments (including printf); otherwise incorrect code
will be generated for calls to those functions.
In addition, seriously incorrect code will result if you call a function
with too many arguments. (Normally, extra arguments are harmlessly
ignored.)
-mregparm=num
Control how many registers are used to pass integer arguments. By default,
no registers are used to pass arguments, and at most 3 registers can be
used. You can control this behavior for a specific function by using the
function attribute regparm.
Warning: if you use this switch, and num is nonzero, then you must build
all modules with the same value, including any libraries. This includes
the system libraries and startup modules.
-mpreferred-stack-boundary=num
Attempt to keep the stack boundary aligned to a 2 raised to num byte
boundary. If -mpreferred-stack-boundary is not specified, the default is 4
(16 bytes or 128 bits), except when optimizing for code size (-Os), in
which case the default is the minimum correct alignment (4 bytes for x86,
and 8 bytes for x86-64).
On Pentium and PentiumPro, double and long double values should be aligned
to an 8 byte boundary (see -malign-double) or suffer significant run time
performance penalties. On Pentium III, the Streaming SIMD Extension ( SSE
) data type __m128 suffers similar penalties if it is not 16 byte aligned.
To ensure proper alignment of this values on the stack, the stack boundary
must be as aligned as that required by any value stored on the stack.
Further, every function must be generated such that it keeps the stack
aligned. Thus calling a function compiled with a higher preferred stack
boundary from a function compiled with a lower preferred stack boundary
will most likely misalign the stack. It is recommended that libraries that
use callbacks always use the default setting.
This extra alignment does consume extra stack space, and generally
increases code size. Code that is sensitive to stack space usage, such as
embedded systems and operating system kernels, may want to reduce the
preferred alignment to -mpreferred-stack-boundary=2.
-mmmx
-mno-mmx
-msse
-mno-sse
-msse2
-mno-sse2
-m3dnow
-mno-3dnow
These switches enable or disable the use of built-in functions that allow
direct access to the MMX, SSE and 3Dnow extensions of the instruction set.
To have SSE/SSE2 instructions generated automatically from floating-point
code, see -mfpmath=sse.
-mpush-args
-mno-push-args
Use PUSH operations to store outgoing parameters. This method is shorter
and usually equally fast as method using SUB/MOV operations and is enabled
by default. In some cases disabling it may improve performance because of
improved scheduling and reduced dependencies.
-maccumulate-outgoing-args
If enabled, the maximum amount of space required for outgoing arguments
will be computed in the function prologue. This is faster on most modern
CPUs because of reduced dependencies, improved scheduling and reduced
stack usage when preferred stack boundary is not equal to 2. The drawback
is a notable increase in code size. This switch implies -mno-push-args.
-mthreads
Support thread-safe exception handling on Mingw32. Code that relies on
thread-safe exception handling must compile and link all code with the -
mthreads option. When compiling, -mthreads defines -D_MT; when linking, it
links in a special thread helper library -lmingwthrd which cleans up per
thread exception handling data.
-mno-align-stringops
Do not align destination of inlined string operations. This switch reduces
code size and improves performance in case the destination is already
aligned, but gcc don't know about it.
-minline-all-stringops
By default GCC inlines string operations only when destination is known to
be aligned at least to 4 byte boundary. This enables more inlining,
increase code size, but may improve performance of code that depends on
fast memcpy, strlen and memset for short lengths.
-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 -fomit-frame-
pointer removes the frame pointer for all functions which might make
debugging harder.
These -m switches are supported in addition to the above on AMD x86-64
processors in 64-bit environments.
-m32
-m64
Generate code for a 32-bit or 64-bit environment. The 32-bit environment
sets int, long and pointer to 32 bits and generates code that runs on any
i386 system. The 64-bit environment sets int to 32 bits and long and
pointer to 64 bits and generates code for AMD's x86-64 architecture.
-mno-red-zone
Do not use a so called red zone for x86-64 code. The red zone is mandated
by the x86-64 ABI, it is a 128-byte area beyond the location of the stack
pointer that will not be modified by signal or interrupt handlers and
therefore can be used for temporary data without adjusting the stack
pointer. The flag -mno-red-zone disables this red zone.
-mcmodel=small
Generate code for the small code model: the program and its symbols must
be linked in the lower 2 GB of the address space. Pointers are 64 bits.
Programs can be statically or dynamically linked. This is the default code
model.
-mcmodel=kernel
Generate code for the kernel code model. The kernel runs in the negative 2
GB of the address space. This model has to be used for Linux kernel code.
-mcmodel=medium
Generate code for the medium model: The program is linked in the lower 2
GB of the address space but symbols can be located anywhere in the address
space. Programs can be statically or dynamically linked, but building of
shared libraries are not supported with the medium model.
-mcmodel=large
Generate code for the large model: This model makes no assumptions about
addresses and sizes of sections. Currently GCC does not implement this
model.
Options for Code Generation Conventions
These machine-independent options control the interface conventions used
in code generation.
Most of them have both positive and negative forms; the negative form of -
ffoo would be -fno-foo. In the table below, only one of the forms is
listed---the one which is not the default. You can figure out the other
form by either removing no- or adding it.
-fbounds-check
For front-ends that support it, generate additional code to check that
indices used to access arrays are within the declared range. This is
currently only supported by the Java and Fortran 77 front-ends, where
this option defaults to true and false respectively.
-ftrapv
This option generates traps for signed overflow on addition,
subtraction, multiplication operations.
-fexceptions
Enable exception handling. Generates extra code needed to propagate
exceptions. For some targets, this implies GCC will generate frame
unwind information for all functions, which can produce significant
data size overhead, although it does not affect execution. If you do
not specify this option, GCC will enable it by default for languages
like C++ which normally require exception handling, and disable it for
languages like C that do not normally require it. However, you may
need to enable this option when compiling C code that needs to
interoperate properly with exception handlers written in C++. You may
also wish to disable this option if you are compiling older C++
programs that don't use exception handling.
-fnon-call-exceptions
Generate code that allows trapping instructions to throw exceptions.
Note that this requires platform-specific runtime support that does
not exist everywhere. Moreover, it only allows trapping instructions
to throw exceptions, i.e. memory references or floating point
instructions. It does not allow exceptions to be thrown from arbitrary
signal handlers such as SIGALRM.
-funwind-tables
Similar to -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.
-fasynchronous-unwind-tables
Generate unwind table in dwarf2 format, if supported by target
machine. The table is exact at each instruction boundary, so it can be
used for stack unwinding from asynchronous events (such as debugger or
garbage collector).
-fpcc-struct-return
Return "short" struct and union values in memory like longer ones,
rather than in registers. This convention is less efficient, but it
has the advantage of allowing intercallability between GCC-compiled
files and files compiled with other compilers, particularly the
Portable C Compiler (pcc).
The precise convention for returning structures in memory depends on
the target configuration macros.
Short structures and unions are those whose size and alignment match
that of some integer type.
Warning: code compiled with the -fpcc-struct-return switch is not
binary compatible with code compiled with the -freg-struct-return
switch. Use it to conform to a non-default application binary
interface.
-freg-struct-return
Return struct and union values in registers when possible. This is
more efficient for small structures than -fpcc-struct-return.
If you specify neither -fpcc-struct-return nor -freg-struct-return,
GCC defaults to whichever convention is standard for the target. If
there is no standard convention, GCC defaults to -fpcc-struct-return,
except on targets where GCC is the principal compiler. In those cases,
we can choose the standard, and we chose the more efficient register
return alternative.
Warning: code compiled with the -freg-struct-return switch is not
binary compatible with code compiled with the -fpcc-struct-return
switch. Use it to conform to a non-default application binary
interface.
-fshort-enums
Allocate to an enum type only as many bytes as it needs for the
declared range of possible values. Specifically, the enum type will be
equivalent to the smallest integer type which has enough room.
Warning: the -fshort-enums switch causes GCC to generate code that is
not binary compatible with code generated without that switch. Use it
to conform to a non-default application binary interface.
-fshort-double
Use the same size for double as for float.
Warning: the -fshort-double switch causes GCC to generate code that is
not binary compatible with code generated without that switch. Use it
to conform to a non-default application binary interface.
-fshort-wchar
Override the underlying type for wchar_t to be short unsigned int
instead of the default for the target. This option is useful for
building programs to run under WINE.
Warning: the -fshort-wchar switch causes GCC to generate code that is
not binary compatible with code generated without that switch. Use it
to conform to a non-default application binary interface.
-fshared-data
Requests that the data and non-const variables of this compilation be
shared data rather than private data. The distinction makes sense only
on certain operating systems, where shared data is shared between
processes running the same program, while private data exists in one
copy per process.
-fno-common
In C, allocate even uninitialized global variables in the data section
of the object file, rather than generating them as common blocks. This
has the effect that if the same variable is declared (without extern)
in two different compilations, you will get an error when you link
them. The only reason this might be useful is if you wish to verify
that the program will work on other systems which always work this
way.
-fno-ident
Ignore the #ident directive.
-fno-gnu-linker
Do not output global initializations (such as C++ constructors and
destructors) in the form used by the GNU linker (on systems where the
GNU linker is the standard method of handling them). Use this option
when you want to use a non-GNU linker, which also requires using the
collect2 program to make sure the system linker includes constructors
and destructors. (collect2 is included in the GCC distribution.) For
systems which must use collect2, the compiler driver gcc is configured
to do this automatically.
-finhibit-size-directive
Don't output a .size assembler directive, or anything else that would
cause trouble if the function is split in the middle, and the two
halves are placed at locations far apart in memory. This option is
used when compiling crtstuff.c; you should not need to use it for
anything else.
-fverbose-asm
Put extra commentary information in the generated assembly code to
make it more readable. This option is generally only of use to those
who actually need to read the generated assembly code (perhaps while
debugging the compiler itself).
-fno-verbose-asm, the default, causes the extra information to be
omitted and is useful when comparing two assembler files.
-fvolatile
Consider all memory references through pointers to be volatile.
-fvolatile-global
Consider all memory references to extern and global data items to be
volatile. GCC does not consider static data items to be volatile
because of this switch.
-fvolatile-static
Consider all memory references to static data to be volatile.
-fpic
Generate position-independent code ( PIC ) suitable for use in a
shared library, if supported for the target machine. Such code
accesses all constant addresses through a global offset table ( GOT ).
The dynamic loader resolves the GOT entries when the program starts
(the dynamic loader is not part of GCC ; it is part of the operating
system). If the GOT size for the linked executable exceeds a machine-
specific maximum size, you get an error message from the linker
indicating that -fpic does not work; in that case, recompile with -
fPIC instead. (These maximums are 16k on the m88k, 8k on the SPARC,
and 32k on the m68k and RS/6000. The 386 has no such limit.)
Position-independent code requires special support, and therefore
works only on certain machines. For the 386, GCC supports PIC for
System V but not for the Sun 386i. Code generated for the IBM RS/6000
is always position-independent.
-fPIC
If supported for the target machine, emit position-independent code,
suitable for dynamic linking and avoiding any limit on the size of the
global offset table. This option makes a difference on the m68k, m88k,
and the SPARC.
Position-independent code requires special support, and therefore
works only on certain machines.
-ffixed-reg
Treat the register named reg as a fixed register; generated code
should never refer to it (except perhaps as a stack pointer, frame
pointer or in some other fixed role).
reg must be the name of a register. The register names accepted are
machine-specific and are defined in the REGISTER_NAMES macro in the
machine description macro file.
This flag does not have a negative form, because it specifies a three-
way choice.
-fcall-used-reg
Treat the register named reg as an allocable register that is
clobbered by function calls. It may be allocated for temporaries or
variables that do not live across a call. Functions compiled this way
will not save and restore the register reg.
It is an error to used this flag with the frame pointer or stack
pointer. Use of this flag for other registers that have fixed
pervasive roles in the machine's execution model will produce
disastrous results.
This flag does not have a negative form, because it specifies a three-
way choice.
-fcall-saved-reg
Treat the register named reg as an allocable register saved by
functions. It may be allocated even for temporaries or variables that
live across a call. Functions compiled this way will save and restore
the register reg if they use it.
It is an error to used this flag with the frame pointer or stack
pointer. Use of this flag for other registers that have fixed
pervasive roles in the machine's execution model will produce
disastrous results.
A different sort of disaster will result from the use of this flag for
a register in which function values may be returned.
This flag does not have a negative form, because it specifies a three-
way choice.
-fpack-struct
Pack all structure members together without holes.
Warning: the -fpack-struct switch causes GCC to generate code that is
not binary compatible with code generated without that switch.
Additionally, it makes the code suboptimal. Use it to conform to a
non-default application binary interface.
-finstrument-functions
Generate instrumentation calls for entry and exit to functions. Just
after function entry and just before function exit, the following
profiling functions will be called with the address of the current
function and its call site. (On some platforms,
__builtin_return_address does not work beyond the current function, so
the call site information may not be available to the profiling
functions otherwise.)
void __cyg_profile_func_enter (void *this_fn,
void *call_site);
void __cyg_profile_func_exit (void *this_fn,
void *call_site);
The first argument is the address of the start of the current
function, which may be looked up exactly in the symbol table.
This instrumentation is also done for functions expanded inline in
other functions. The profiling calls will indicate where,
conceptually, the inline function is entered and exited. This means
that addressable versions of such functions must be available. If all
your uses of a function are expanded inline, this may mean an
additional expansion of code size. If you use extern inline in your C
code, an addressable version of such functions must be provided. (This
is normally the case anyways, but if you get lucky and the optimizer
always expands the functions inline, you might have gotten away
without providing static copies.)
A function may be given the attribute no_instrument_function, in which
case this instrumentation will not be done. This can be used, for
example, for the profiling functions listed above, high-priority
interrupt routines, and any functions from which the profiling
functions cannot safely be called (perhaps signal handlers, if the
profiling routines generate output or allocate memory).
-fstack-check
Generate code to verify that you do not go beyond the boundary of the
stack. You should specify this flag if you are running in an
environment with multiple threads, but only rarely need to specify it
in a single-threaded environment since stack overflow is automatically
detected on nearly all systems if there is only one stack.
Note that this switch does not actually cause checking to be done; the
operating system must do that. The switch causes generation of code to
ensure that the operating system sees the stack being extended.
-fstack-limit-register=reg
-fstack-limit-symbol=sym
-fno-stack-limit
Generate code to ensure that the stack does not grow beyond a certain
value, either the value of a register or the address of a symbol. If
the stack would grow beyond the value, a signal is raised. For most
targets, the signal is raised before the stack overruns the boundary,
so it is possible to catch the signal without taking special
precautions.
For instance, if the stack starts at absolute address 0x80000000 and
grows downwards, you can use the flags -fstack-limit-
symbol=__stack_limit and -Wl,--defsym,__stack_limit=0x7ffe0000 to
enforce a stack limit of 128KB. Note that this may only work with the
GNU linker.
-fargument-alias
-fargument-noalias
-fargument-noalias-global
Specify the possible relationships among parameters and between
parameters and global data.
-fargument-alias specifies that arguments (parameters) may alias each
other and may alias global storage.-fargument-noalias specifies that
arguments do not alias each other, but may alias global storage.-
fargument-noalias-global specifies that arguments do not alias each
other and do not alias global storage.
Each language will automatically use whatever option is required by
the language standard. You should not need to use these options
yourself.
-fleading-underscore
This option and its counterpart, -fno-leading-underscore, forcibly
change the way C symbols are represented in the object file. One use
is to help link with legacy assembly code.
Warning: the -fleading-underscore switch causes GCC to generate code
that is not binary compatible with code generated without that switch.
Use it to conform to a non-default application binary interface. Not
all targets provide complete support for this switch.
-ftls-model=model
Alter the thread-local storage model to be used. The model argument
should be one of global-dynamic, local-dynamic, initial-exec or local-
exec.
The default without -fpic is initial-exec; with -fpic the default is
global-dynamic.
ENVIRONMENT
This section describes several environment variables that affect how GCC
operates. Some of them work by specifying directories or prefixes to use
when searching for various kinds of files. Some are used to specify other
aspects of the compilation environment.
Note that you can also specify places to search using options such as -B,
-I and -L. These take precedence over places specified using environment
variables, which in turn take precedence over those specified by the
configuration of GCC.
LANG
LC_CTYPE
LC_MESSAGES
LC_ALL
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 LC_CTYPE and
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 en_UK for English in the United Kingdom.
The 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 LC_MESSAGES environment variable specifies the language to use in
diagnostic messages.
If the LC_ALL environment variable is set, it overrides the value of
LC_CTYPE and LC_MESSAGES ; otherwise, LC_CTYPE and LC_MESSAGES default
to the value of the LANG environment variable. If none of these
variables are set, GCC defaults to traditional C English behavior.
TMPDIR
If TMPDIR is set, it specifies the directory to use for temporary
files. GCC uses temporary files to hold the output of one stage of
compilation which is to be used as input to the next stage: for
example, the output of the preprocessor, which is the input to the
compiler proper.
GCC_EXEC_PREFIX
If 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 GCC_EXEC_PREFIX is not set, GCC will attempt to figure out an
appropriate prefix to use based on the pathname it was invoked with.
If GCC cannot find the subprogram using the specified prefix, it tries
looking in the usual places for the subprogram.
The default value of GCC_EXEC_PREFIX is prefix/lib/gcc-lib/ where
prefix is the value of prefix when you ran the configure script.
Other prefixes specified with -B take precedence over this prefix.
This prefix is also used for finding files such as crt0.o that are
used for linking.
In addition, the prefix is used in an unusual way in finding the
directories to search for header files. For each of the standard
directories whose name normally begins with /usr/local/lib/gcc-lib
(more precisely, with the value of GCC_INCLUDE_DIR ), GCC tries
replacing that beginning with the specified prefix to produce an
alternate directory name. Thus, with -Bfoo/, GCC will search foo/bar
where it would normally search /usr/local/lib/bar. These alternate
directories are searched first; the standard directories come next.
COMPILER_PATH
The value of COMPILER_PATH is a colon-separated list of directories,
much like PATH. GCC tries the directories thus specified when
searching for subprograms, if it can't find the subprograms using
GCC_EXEC_PREFIX.
LIBRARY_PATH
The value of LIBRARY_PATH is a colon-separated list of directories,
much like 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 GCC_EXEC_PREFIX. Linking using GCC also uses
these directories when searching for ordinary libraries for the -
l option (but directories specified with -L come first).
LANG
This variable is used to pass locale information to the compiler. One
way in which this information is used is to determine the character
set to be used when character literals, string literals and comments
are parsed in C and C++. When the compiler is configured to allow
multibyte characters, the following values for LANG are recognized:
C-EUCJP
Recognize EUCJP characters.
If 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.
Some additional environments variables affect the behavior of the
preprocessor.
CPATH
C_INCLUDE_PATH
CPLUS_INCLUDE_PATH
OBJC_INCLUDE_PATH
Each variable's value is a list of directories separated by a special
character, much like PATH, in which to look for header files. The
special character, PATH_SEPARATOR, is target-dependent and determined
at GCC build time. For Windows-based targets it is a semicolon, and
for almost all other targets it is a colon.
CPATH specifies a list of directories to be searched as if specified
with -I, but after any paths given with -I options on the command
line. This environment variable is used regardless of which language
is being preprocessed.
The remaining environment variables apply only when preprocessing the
particular language indicated. Each specifies a list of directories to
be searched as if specified with -isystem, but after any paths given
with -isystem options on the command line.
In all these variables, an empty element instructs the compiler to
search its current working directory. Empty elements can appear at the
beginning or end of a path. For instance, if the value of CPATH is :/
special/include, that has the same effect as -I. -I/special/include.
DEPENDENCIES_OUTPUT
If this variable is set, its value specifies how to output
dependencies for Make based on the non-system header files processed
by the compiler. System header files are ignored in the dependency
output.
The value of 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 file target,
in which case the rules are written to file file using target as the
target name.
In other words, this environment variable is equivalent to combining
the options -MM and -MF, with an optional -MT switch too.
SUNPRO_DEPENDENCIES
This variable is the same as DEPENDENCIES_OUTPUT (see above), except
that system header files are not ignored, so it implies -M rather than
-MM. However, the dependence on the main input file is omitted.
BUGS
For instructions on reporting bugs, see http://gcc.gnu.org/bugs.html;. Use
of the gccbug script to report bugs is recommended.
FOOTNOTES
1.
On some systems, gcc -shared needs to build supplementary stub code for
constructors to work. On multi-libbed systems, 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.
SEE ALSO
cpp(1)
gcov(1)
g77(1)
as(1)
ld(1)
gdb(1)
AUTHOR
See http://gcc.gnu.org/onlinedocs/gcc/Contributors.html for contributors
to GCC.
COPYRIGHT
Copyright (c) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000, 2001, 2002, 2003 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or any
later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License" and "Funding Free
Software", the Front-Cover texts being (a) (see below), and with the Back-
Cover Texts being (b) (see below). A copy of the license is included in
the gfdl(7) man page.
(a) The FSF's Front-Cover Text is:
A GNU Manual
(b) The FSF's Back-Cover Text is:
You have freedom to copy and modify this GNU Manual, like GNU
software. Copies published by the Free Software Foundation raise
funds for GNU development.