(gcc.info.gz) Code Gen Options
Info Catalog
(gcc.info.gz) Submodel Options
(gcc.info.gz) Invoking GCC
(gcc.info.gz) Environment Variables
3.18 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
front-ends, where this option defaults to true and false
respectively.
`-ftrapv'
This option generates traps for signed overflow on addition,
subtraction, multiplication operations.
`-fwrapv'
This option instructs the compiler to assume that signed arithmetic
overflow of addition, subtraction and multiplication wraps around
using twos-complement representation. This flag enables some
optimizations and disables others. This option is enabled by
default for the Java front-end, as required by the Java language
specification.
`-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.
`-fno-common'
In C code, controls the placement of uninitialized global
variables. Unix C compilers have traditionally permitted multiple
definitions of such variables in different compilation units by
placing the variables in a common block. This is the behavior
specified by `-fcommon', and is the default for GCC on most
targets. On the other hand, this behavior is not required by ISO
C, and on some targets may carry a speed or code size penalty on
variable references. The `-fno-common' option specifies that the
compiler should place 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 a
multiple-definition error when you link them. In this case, you
must compile with `-fcommon' instead. Compiling with
`-fno-common' is useful on targets for which it provides better
performance, or if you wish to verify that the program will work
on other systems which always treat uninitialized variable
declarations this way.
`-fno-ident'
Ignore the `#ident' directive.
`-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.
`-frecord-gcc-switches'
This switch causes the command line that was used to invoke the
compiler to be recorded into the object file that is being created.
This switch is only implemented on some targets and the exact
format of the recording is target and binary file format
dependent, but it usually takes the form of a section containing
ASCII text. This switch is related to the `-fverbose-asm' switch,
but that switch only records information in the assembler output
file as comments, so it never reaches the object file.
`-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 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.
When this flag is set, the macros `__pic__' and `__PIC__' are
defined to 1.
`-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, PowerPC and SPARC.
Position-independent code requires special support, and therefore
works only on certain machines.
When this flag is set, the macros `__pic__' and `__PIC__' are
defined to 2.
`-fpie'
`-fPIE'
These options are similar to `-fpic' and `-fPIC', but generated
position independent code can be only linked into executables.
Usually these options are used when `-pie' GCC option will be used
during linking.
`-fpie' and `-fPIE' both define the macros `__pie__' and
`__PIE__'. The macros have the value 1 for `-fpie' and 2 for
`-fPIE'.
`-fno-jump-tables'
Do not use jump tables for switch statements even where it would be
more efficient than other code generation strategies. This option
is of use in conjunction with `-fpic' or `-fPIC' for building code
which forms part of a dynamic linker and cannot reference the
address of a jump table. On some targets, jump tables do not
require a GOT and this option is not needed.
`-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[=N]'
Without a value specified, pack all structure members together
without holes. When a value is specified (which must be a small
power of two), pack structure members according to this value,
representing the maximum alignment (that is, objects with default
alignment requirements larger than this will be output potentially
unaligned at the next fitting location.
*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).
`-finstrument-functions-exclude-file-list=FILE,FILE,...'
Set the list of functions that are excluded from instrumentation
(see the description of `-finstrument-functions'). If the file
that contains a function definition matches with one of FILE, then
that function is not instrumented. The match is done on
substrings: if the FILE parameter is a substring of the file name,
it is considered to be a match.
For example,
`-finstrument-functions-exclude-file-list=/bits/stl,include/sys'
will exclude any inline function defined in files whose pathnames
contain `/bits/stl' or `include/sys'.
If, for some reason, you want to include letter `','' in one of
SYM, write `'\,''. For example,
`-finstrument-functions-exclude-file-list='\,\,tmp'' (note the
single quote surrounding the option).
`-finstrument-functions-exclude-function-list=SYM,SYM,...'
This is similar to `-finstrument-functions-exclude-file-list', but
this option sets the list of function names to be excluded from
instrumentation. The function name to be matched is its
user-visible name, such as `vector<int> blah(const vector<int>
&)', not the internal mangled name (e.g.,
`_Z4blahRSt6vectorIiSaIiEE'). The match is done on substrings: if
the SYM parameter is a substring of the function name, it is
considered to be a match.
`-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 or the language runtime must do that. The
switch causes generation of code to ensure that they see the stack
being extended.
You can additionally specify a string parameter: `no' means no
checking, `generic' means force the use of old-style checking,
`specific' means use the best checking method and is equivalent to
bare `-fstack-check'.
Old-style checking is a generic mechanism that requires no specific
target support in the compiler but comes with the following
drawbacks:
1. Modified allocation strategy for large objects: they will
always be allocated dynamically if their size exceeds a fixed
threshold.
2. Fixed limit on the size of the static frame of functions:
when it is topped by a particular function, stack checking is
not reliable and a warning is issued by the compiler.
3. Inefficiency: because of both the modified allocation
strategy and the generic implementation, the performances of
the code are hampered.
Note that old-style stack checking is also the fallback method for
`specific' if no target support has been added in the compiler.
`-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'
`-fargument-noalias-anything'
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.
`-fargument-noalias-anything' specifies that arguments do not
alias any other 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 (
Thread-Local). 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'.
`-fvisibility=DEFAULT|INTERNAL|HIDDEN|PROTECTED'
Set the default ELF image symbol visibility to the specified
option--all symbols will be marked with this unless overridden
within the code. Using this feature can very substantially
improve linking and load times of shared object libraries, produce
more optimized code, provide near-perfect API export and prevent
symbol clashes. It is *strongly* recommended that you use this in
any shared objects you distribute.
Despite the nomenclature, `default' always means public ie;
available to be linked against from outside the shared object.
`protected' and `internal' are pretty useless in real-world usage
so the only other commonly used option will be `hidden'. The
default if `-fvisibility' isn't specified is `default', i.e., make
every symbol public--this causes the same behavior as previous
versions of GCC.
A good explanation of the benefits offered by ensuring ELF symbols
have the correct visibility is given by "How To Write Shared
Libraries" by Ulrich Drepper (which can be found at
`http://people.redhat.com/~drepper/')--however a superior solution
made possible by this option to marking things hidden when the
default is public is to make the default hidden and mark things
public. This is the norm with DLL's on Windows and with
`-fvisibility=hidden' and `__attribute__
((visibility("default")))' instead of `__declspec(dllexport)' you
get almost identical semantics with identical syntax. This is a
great boon to those working with cross-platform projects.
For those adding visibility support to existing code, you may find
`#pragma GCC visibility' of use. This works by you enclosing the
declarations you wish to set visibility for with (for example)
`#pragma GCC visibility push(hidden)' and `#pragma GCC visibility
pop'. Bear in mind that symbol visibility should be viewed *as
part of the API interface contract* and thus all new code should
always specify visibility when it is not the default ie;
declarations only for use within the local DSO should *always* be
marked explicitly as hidden as so to avoid PLT indirection
overheads--making this abundantly clear also aids readability and
self-documentation of the code. Note that due to ISO C++
specification requirements, operator new and operator delete must
always be of default visibility.
Be aware that headers from outside your project, in particular
system headers and headers from any other library you use, may not
be expecting to be compiled with visibility other than the
default. You may need to explicitly say `#pragma GCC visibility
push(default)' before including any such headers.
`extern' declarations are not affected by `-fvisibility', so a lot
of code can be recompiled with `-fvisibility=hidden' with no
modifications. However, this means that calls to `extern'
functions with no explicit visibility will use the PLT, so it is
more effective to use `__attribute ((visibility))' and/or `#pragma
GCC visibility' to tell the compiler which `extern' declarations
should be treated as hidden.
Note that `-fvisibility' does affect C++ vague linkage entities.
This means that, for instance, an exception class that will be
thrown between DSOs must be explicitly marked with default
visibility so that the `type_info' nodes will be unified between
the DSOs.
An overview of these techniques, their benefits and how to use them
is at `http://gcc.gnu.org/wiki/Visibility'.
Info Catalog
(gcc.info.gz) Submodel Options
(gcc.info.gz) Invoking GCC
(gcc.info.gz) Environment Variables
automatically generated by
info2html