Next:GCC Developer Options, Previous:Options for use with Picolibc, Up:GCC Command Options [Contents][Index]
These machine-independent options control the interface conventionsused in code generation.
Most of them have both positive and negative forms; the negative formof-ffoo is-fno-foo. In the table below, onlyone of the forms is listed—the one that is not the default. Youcan figure out the other form by either removing ‘no-’ or addingit.
-fstack-reuse=reuse-level ¶This option controls stack space reuse for user declared local/auto variablesand compiler generated temporaries.reuse_level can be ‘all’,‘named_vars’, or ‘none’. ‘all’ enables stack reuse for alllocal variables and temporaries, ‘named_vars’ enables the reuse only foruser defined local variables with names, and ‘none’ disables stack reusecompletely. The default value is ‘all’. The option is needed when theprogram extends the lifetime of a scoped local variable or a compiler generatedtemporary beyond the end point defined by the language. When a lifetime ofa variable ends, and if the variable lives in memory, the optimizing compilerhas the freedom to reuse its stack space with other temporaries or scopedlocal variables whose live range does not overlap with it. Legacy code extendinglocal lifetime is likely to break with the stack reuse optimization.
For example,
int *p; { int local1; p = &local1; local1 = 10; .... } { int local2; local2 = 20; ... } if (*p == 10) // out of scope use of local1 { }Another example:
struct A { A(int k) : i(k), j(k) { } int i; int j; }; A *ap; void foo(const A& ar) { ap = &ar; } void bar() { foo(A(10)); // temp object's lifetime ends when foo returns { A a(20); .... } ap->i+= 10; // ap references out of scope temp whose space // is reused with a. What is the value of ap->i? }The lifetime of a compiler generated temporary is well defined by the C++standard. When a lifetime of a temporary ends, and if the temporary livesin memory, the optimizing compiler has the freedom to reuse its stackspace with other temporaries or scoped local variables whose live rangedoes not overlap with it. However some of the legacy code relies onthe behavior of older compilers in which temporaries’ stack space isnot reused, the aggressive stack reuse can lead to runtime errors. Thisoption is used to control the temporary stack reuse optimization.
-ftrapv ¶This option generates traps for signed overflow on addition, subtraction,multiplication operations.The options-ftrapv and-fwrapv override each other, so using-ftrapv-fwrapv on the command-line results in-fwrapv being effective. Note that only active options override, sousing-ftrapv-fwrapv-fno-wrapv on the command-lineresults in-ftrapv being effective.
-fwrapv ¶This option instructs the compiler to assume that signed arithmeticoverflow of addition, subtraction and multiplication wraps aroundusing twos-complement representation. This flag enables some optimizationsand disables others.The options-ftrapv and-fwrapv override each other, so using-ftrapv-fwrapv on the command-line results in-fwrapv being effective. Note that only active options override, sousing-ftrapv-fwrapv-fno-wrapv on the command-lineresults in-ftrapv being effective.
-fwrapv-pointer ¶This option instructs the compiler to assume that pointer arithmeticoverflow on addition and subtraction wraps around using twos-complementrepresentation. This flag disables some optimizations which assumepointer overflow is invalid.
-fstrict-overflow ¶This option implies-fno-wrapv-fno-wrapv-pointer and whennegated implies-fwrapv-fwrapv-pointer.
-fexceptions ¶Enable exception handling. Generates extra code needed to propagateexceptions. For some targets, this implies GCC generates frameunwind information for all functions, which can produce significant datasize overhead, although it does not affect execution. If you do notspecify this option, GCC enables it by default for languages likeC++ that normally require exception handling, and disables it forlanguages like C that do not normally require it. However, you may needto enable this option when compiling C code that needs to interoperateproperly with exception handlers written in C++. You may also wish todisable this option if you are compiling older C++ programs that don’tuse exception handling.
-fnon-call-exceptions ¶Generate code that allows trapping instructions to throw exceptions.Note that this requires platform-specific runtime support that doesnot exist everywhere. Moreover, it only allowstrappinginstructions to throw exceptions, i.e. memory references or floating-pointinstructions. It does not allow exceptions to be thrown fromarbitrary signal handlers such asSIGALRM. This enables-fexceptions.
-fdelete-dead-exceptions ¶Consider that instructions that may throw exceptions but don’t otherwisecontribute to the execution of the program can be optimized away.This does not affect calls to functions except those with thepure orconst attributes.This option is enabled by default for the Ada and C++ compilers, as permitted bythe language specifications.Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels.
-funwind-tables ¶Similar to-fexceptions, except that it just generates any neededstatic data, but does not affect the generated code in any other way.You normally do not need to enable this option; instead, a language processorthat needs this handling enables it on your behalf.
-fasynchronous-unwind-tables ¶Generate unwind table in DWARF format, if supported by target machine. Thetable is exact at each instruction boundary, so it can be used for stackunwinding from asynchronous events (such as debugger or garbage collector).
-fno-gnu-unique ¶On systems with recent GNU assembler and C library, the C++ compileruses theSTB_GNU_UNIQUE binding to make sure that definitionsof template static data members and static local variables in inlinefunctions are unique even in the presence ofRTLD_LOCAL; thisis necessary to avoid problems with a library used by two differentRTLD_LOCAL plugins depending on a definition in one of them andtherefore disagreeing with the other one about the binding of thesymbol. But this causesdlclose to be ignored for affectedDSOs; if your program relies on reinitialization of a DSO viadlclose anddlopen, you can use-fno-gnu-unique.
-fpcc-struct-return ¶Return “short”struct andunion values in memory likelonger ones, rather than in registers. This convention is lessefficient, but it has the advantage of allowing intercallability betweenGCC-compiled files and files compiled with other compilers, particularlythe Portable C Compiler (pcc).
The precise convention for returning structures in memory dependson the target configuration macros.
Short structures and unions are those whose size and alignment matchthat of some integer type.
Warning: code compiled with the-fpcc-struct-returnswitch 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 ¶Returnstruct andunion 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 isstandard for the target. If there is no standard convention, GCCdefaults to-fpcc-struct-return, except on targets where GCC isthe principal compiler. In those cases, we can choose the standard, andwe chose the more efficient register return alternative.
Warning: code compiled with the-freg-struct-returnswitch 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 anenum type only as many bytes as it needs for thedeclared range of possible values. Specifically, theenum typeis equivalent to the smallest integer type that has enough room.This option has no effect for an enumeration type with a fixed underlyingtype.
Warning: the-fshort-enums switch causes GCC to generatecode 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 forwchar_t to beshortunsigned int instead of the default for the target. This option isuseful for building programs to run under WINE.
Warning: the-fshort-wchar switch causes GCC to generatecode that is not binary compatible with code generated without that switch.Use it to conform to a non-default application binary interface.
-fcommon ¶In C code, this option controls the placement of global variablesdefined without an initializer, known astentative definitionsin the C standard. Tentative definitions are distinct from declarationsof a variable with theextern keyword, which do not allocate storage.
The default is-fno-common, which specifies that the compiler placesuninitialized global variables in the BSS section of the object file.This inhibits the merging of tentative definitions by the linker so you get amultiple-definition error if the same variable is accidentally defined in morethan one compilation unit.
The-fcommon places uninitialized global variables in a common block.This allows the linker to resolve all tentative definitions of the same variablein different compilation units to the same object, or to a non-tentativedefinition. This behavior is inconsistent with C++, and on many targets impliesa speed and code size penalty on global variable references. It is mainlyuseful to enable legacy code to link without errors.
-fno-ident ¶-Qy-Qn-fno-ident suppresses emission of.ident assemblerdirectives and causes the#ident preprocessor directive to be ignored.-Qy and-Qn are obsolete synonyms for-fidentand-fno-ident, respectively.
-finhibit-size-directive ¶Don’t output a.size assembler directive, or anything else thatwould cause trouble if the function is split in the middle, and thetwo halves are placed at locations far apart in memory. This option isused when compilingcrtstuff.c; you should not need to use itfor anything else.
-fverbose-asm ¶Put extra commentary information in the generated assembly code tomake it more readable. This option is generally only of use to thosewho actually need to read the generated assembly code (perhaps whiledebugging the compiler itself).
-fno-verbose-asm, the default, causes theextra information to be omitted and is useful when comparing two assemblerfiles.
The added comments include:
For example, given this C source file:
int test (int n){ int i; int total = 0; for (i = 0; i < n; i++) total += i * i; return total;}compiling to (x86_64) assembly via-S and emitting the resultdirect to stdout via-o-
gcc -S test.c -fverbose-asm -Os -o -
gives output similar to this:
.file"test.c"# GNU C11 (GCC) version 7.0.0 20160809 (experimental) (x86_64-pc-linux-gnu) [...snip...]# options passed: [...snip...].text.globltest.typetest, @functiontest:.LFB0:.cfi_startproc# test.c:4: int total = 0;xorl%eax, %eax# <retval># test.c:6: for (i = 0; i < n; i++)xorl%edx, %edx# i.L2:# test.c:6: for (i = 0; i < n; i++)cmpl%edi, %edx# n, ijge.L5#,# test.c:7: total += i * i;movl%edx, %ecx# i, tmp92imull%edx, %ecx# i, tmp92# test.c:6: for (i = 0; i < n; i++)incl%edx# i# test.c:7: total += i * i;addl%ecx, %eax# tmp92, <retval>jmp.L2#.L5:# test.c:10: }ret.cfi_endproc.LFE0:.sizetest, .-test.ident"GCC: (GNU) 7.0.0 20160809 (experimental)".section.note.GNU-stack,"",@progbits
The comments are intended for humans rather than machines and hence theprecise format of the comments is subject to change.
-frecord-gcc-switches ¶This switch causes the command line used to invoke thecompiler to be recorded into the object file that is being created.This switch is only implemented on some targets and the exact formatof the recording is target and binary file format dependent, but itusually takes the form of a section containing ASCII text. Thisswitch is related to the-fverbose-asm switch, but thatswitch only records information in the assembler output file ascomments, so it never reaches the object file.See also-grecord-gcc-switches for anotherway of storing compiler options into the object file.
-fpic ¶Generate position-independent code (PIC) suitable for use in a sharedlibrary, if supported for the target machine. Such code accesses allconstant addresses through a global offset table (GOT). The dynamicloader resolves the GOT entries when the program starts (the dynamicloader is not part of GCC; it is part of the operating system). Ifthe GOT size for the linked executable exceeds a machine-specificmaximum size, you get an error message from the linker indicating that-fpic does not work; in that case, recompile with-fPICinstead. (These maximums are 8k on the SPARC, 28k on AArch64 and 32kon the m68k and RS/6000. The x86 has no such limit.)
Position-independent code requires special support, and therefore worksonly on certain machines. For the x86, GCC supports PIC for System Vbut not for the Sun 386i. Code generated for the IBM RS/6000 is alwaysposition-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 theglobal offset table. This option makes a difference on AArch64, m68k,PowerPC and SPARC.
Position-independent code requires special support, and therefore worksonly on certain machines.
When this flag is set, the macros__pic__ and__PIC__are defined to 2.
-fpie ¶-fPIEThese options are similar to-fpic and-fPIC, but thegenerated position-independent code can be only linked into executables.Usually these options are used to compile code that will be linked usingthe-pie GCC option.
-fpie and-fPIE both define the macros__pie__ and__PIE__. The macros have the value 1for-fpie and 2 for-fPIE.
-fno-plt ¶Do not use the PLT for external function calls in position-independent code.Instead, load the callee address at call sites from the GOT and branch to it.This leads to more efficient code by eliminating PLT stubs and exposingGOT loads to optimizations. On architectures such as 32-bit x86 wherePLT stubs expect the GOT pointer in a specific register, this gives moreregister allocation freedom to the compiler.Lazy binding requires use of the PLT;with-fno-plt all external symbols are resolved at load time.
Alternatively, the function attributenoplt can be used to avoid callsthrough the PLT for specific external functions.
In position-dependent code, a few targets also convert calls tofunctions that are marked to not use the PLT to use the GOT instead.
-fno-jump-tables ¶Do not use jump tables for switch statements even where it would bemore efficient than other code generation strategies. This option isof use in conjunction with-fpic or-fPIC forbuilding code that forms part of a dynamic linker and cannotreference the address of a jump table. On some targets, jump tablesdo not require a GOT and this option is not needed.
-fno-bit-tests ¶Do not use bit tests for switch statements even where it would bemore efficient than other code generation strategies.
-ffixed-reg ¶Treat the register namedreg as a fixed register; generated codeshould never refer to it (except perhaps as a stack pointer, framepointer or in some other fixed role).
reg must be the name of a register. The register names acceptedare machine-specific and are defined in theREGISTER_NAMESmacro in the machine description macro file.
This flag does not have a negative form, because it specifies athree-way choice.
-fcall-used-reg ¶Treat the register namedreg as an allocable register that isclobbered by function calls. It may be allocated for temporaries orvariables that do not live across a call. Functions compiled this waydo not save and restore the registerreg.
It is an error to use this flag with the frame pointer or stack pointer.Use of this flag for other registers that have fixed pervasive roles inthe machine’s execution model produces disastrous results.
This flag does not have a negative form, because it specifies athree-way choice.
-fcall-saved-reg ¶Treat the register namedreg as an allocable register saved byfunctions. It may be allocated even for temporaries or variables thatlive across a call. Functions compiled this way save and restorethe registerreg if they use it.
It is an error to use this flag with the frame pointer or stack pointer.Use of this flag for other registers that have fixed pervasive roles inthe machine’s execution model produces disastrous results.
A different sort of disaster results from the use of this flag fora register in which function values may be returned.
This flag does not have a negative form, because it specifies athree-way choice.
-fpack-struct[=n] ¶Without a value specified, pack all structure members together withoutholes. When a value is specified (which must be a small power of two), packstructure members according to this value, representing the maximumalignment (that is, objects with default alignment requirements larger thanthis are output potentially unaligned at the next fitting location.
Warning: the-fpack-struct switch causes GCC to generatecode 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.
-fleading-underscore ¶This option and its counterpart,-fno-leading-underscore, forciblychange the way C symbols are represented in the object file. One useis to help link with legacy assembly code.
Warning: the-fleading-underscore switch causes GCC togenerate code that is not binary compatible with code generated without thatswitch. 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 (seeThread-Local Storage).Themodel argument should be one of ‘global-dynamic’,‘local-dynamic’, ‘initial-exec’ or ‘local-exec’.Note that the choice is subject to optimization: the compiler may usea more efficient model for symbols not visible outside of the translationunit, or if-fpic is not given on the command line.
The default without-fpic is ‘initial-exec’; with-fpic the default is ‘global-dynamic’.
-ftrampolines ¶For targets that normally need trampolines for nested functions, alwaysgenerate them instead of using descriptors. Otherwise, for targets thatdo not need them, like for example HP-PA or IA-64, do nothing.
A trampoline is a small piece of code that is created at run time on thestack when the address of a nested function is taken, and is used to callthe nested function indirectly. Therefore, it requires the stack to bemade executable in order for the program to work properly.
-fno-trampolines is enabled by default on a language by languagebasis to let the compiler avoid generating them, if it computes that thisis safe, and replace them with descriptors. Descriptors are made up of dataonly, but the generated code must be prepared to deal with them. As of thiswriting,-fno-trampolines is enabled by default only for Ada.
Moreover, code compiled with-ftrampolines and code compiled with-fno-trampolines are not binary compatible if nested functions arepresent. This option must therefore be used on a program-wide basis and bemanipulated with extreme care.
For languages other than Ada, the-ftrampolines and-fno-trampolines options currently have no effect, andtrampolines are always generated on platforms that need themfor nested functions.
-ftrampoline-impl=[stack|heap] ¶By default, trampolines are generated on stack. However, certain platforms(such as the Apple M1) do not permit an executable stack. Compiling with-ftrampoline-impl=heap generate calls to__gcc_nested_func_ptr_created and__gcc_nested_func_ptr_deleted in order to allocate anddeallocate trampoline space on the executable heap. These functions areimplemented in libgcc, and will only be provided on specific targets:x86_64 Darwin, x86_64 and aarch64 Linux.PLEASE NOTE: Heaptrampolines arenot guaranteed to be correctly deallocated if yousetjmp, instantiate nested functions, and thenlongjmp backto a state prior to having allocated those nested functions.
-fvisibility=[default|internal|hidden|protected] ¶Set the default ELF image symbol visibility to the specified option—allsymbols are marked with this unless overridden within the code.Using this feature can very substantially improve linking andload times of shared object libraries, produce more optimizedcode, provide near-perfect API export and prevent symbol clashes.It isstrongly recommended that you use this in any shared objectsyou distribute.
Despite the nomenclature, ‘default’ always means public; i.e.,available to be linked against from outside the shared object.‘protected’ and ‘internal’ are pretty useless in real-worldusage so the only other commonly used option is ‘hidden’.The default if-fvisibility isn’t specified is‘default’, i.e., make every symbol public.
A good explanation of the benefits offered by ensuring ELFsymbols have the correct visibility is given by “How To WriteShared Libraries” by Ulrich Drepper (which can be found athttps://www.akkadia.org/drepper/)—however a superiorsolution made possible by this option to marking things hidden whenthe default is public is to make the default hidden and mark thingspublic. This is the norm with DLLs on Windows and with-fvisibility=hiddenand__attribute__ ((visibility("default"))) instead of__declspec(dllexport) you get almost identical semantics withidentical syntax. This is a great boon to those working withcross-platform projects.
For those adding visibility support to existing code, you may find#pragma GCC visibility of use. This works by you enclosingthe 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 viewedaspart of the API interface contract and thus all new code shouldalways specify visibility when it is not the default; i.e., declarationsonly for use within the local DSO shouldalways be marked explicitlyas hidden as so to avoid PLT indirection overheads—making thisabundantly clear also aids readability and self-documentation of the code.Note that due to ISO C++ specification requirements,operator new andoperator delete must always be of default visibility.
Be aware that headers from outside your project, in particular systemheaders and headers from any other library you use, may not beexpecting to be compiled with visibility other than the default. Youmay need to explicitly say#pragma GCC visibility push(default)before including any such headers.
extern declarations are not affected by-fvisibility, soa lot of code can be recompiled with-fvisibility=hidden withno modifications. However, this means that calls toexternfunctions with no explicit visibility use the PLT, so it is moreeffective to use__attribute ((visibility)) and/or#pragma GCC visibility to tell the compiler whichexterndeclarations should be treated as hidden.
Note that-fvisibility does affect C++ vague linkageentities. This means that, for instance, an exception class that isbe thrown between DSOs must be explicitly marked with defaultvisibility so that the ‘type_info’ nodes are unified betweenthe DSOs.
An overview of these techniques, their benefits and how to use themis athttps://gcc.gnu.org/wiki/Visibility.
-fstrict-volatile-bitfields ¶This option should be used if accesses to volatile bit-fields (or otherstructure fields, although the compiler usually honors those typesanyway) should use a single access of the width of thefield’s type, aligned to a natural alignment if possible. Forexample, targets with memory-mapped peripheral registers might requireall such accesses to be 16 bits wide; with this flag you candeclare all peripheral bit-fields asunsigned short (assuming shortis 16 bits on these targets) to force GCC to use 16-bit accessesinstead of, perhaps, a more efficient 32-bit access.
If this option is disabled, the compiler uses the most efficientinstruction. In the previous example, that might be a 32-bit loadinstruction, even though that accesses bytes that do not containany portion of the bit-field, or memory-mapped registers unrelated tothe one being updated.
In some cases, such as when thepacked attribute is applied to astructure field, it may not be possible to access the field with a singleread or write that is correctly aligned for the target machine. In thiscase GCC falls back to generating multiple accesses rather than code thatwill fault or truncate the result at run time.
Note: Due to restrictions of the C/C++11 memory model, write accesses arenot allowed to touch non bit-field members. It is therefore recommendedto define all bits of the field’s type as bit-field members.
The default value of this option is determined by the application binaryinterface for the target processor.
-fsync-libcalls ¶This option controls whether any out-of-line instance of the__syncfamily of functions may be used to implement the C++11__atomicfamily of functions.
The default value of this option is enabled, thus the only useful formof the option is-fno-sync-libcalls. This option is used inthe implementation of thelibatomic runtime library.
-fzero-init-padding-bits=value ¶Guarantee zero initialization of padding bits in automatic variableinitializers.Certain languages guarantee zero initialization of padding bits incertain cases, e.g. C23 when using empty initializers ({}),or C++ when using zero-initialization or C guarantees that fieldsnot specified in an initializer have their padding bits zero initialized.This option allows to change when padding bits in initializers areguaranteed to be zero initialized.The default is-fzero-init-padding-bits=standard, which makesno further guarantees than the corresponding standard. E.g.
struct A { char a; unsigned long long b; char c; }; union B { char a; unsigned long long b; }; struct A a = {}; // C23 guarantees padding bits are zero. struct A b = { 1, 2, 3 }; // No guarantees. union B c = {}; // C23 guarantees padding bits are zero. union B d = { 1 }; // No guarantees.-fzero-init-padding-bits=unions guarantees zero initializationof padding bits in unions on top of what the standards guarantee,if the initializer of an union is empty (then all bits of the unionare zero initialized) or if the initialized member of the union issmaller than the size of the union (in that case guarantees paddingbits outside of the initialized member to be zero initialized).This was the GCC behavior before GCC 15 and in the above example guaranteeszero initialization of lastsizeof (unsigned long long) - 1bytes in the union.
-fzero-init-padding-bits=all guarantees additionallyzero initialization of padding bits of other aggregates, sothe padding in betweenb.a andb.b (if any) andtail padding in the structure (if any).
Next:GCC Developer Options, Previous:Options for use with Picolibc, Up:GCC Command Options [Contents][Index]