path: root/devdocs/gcc~13/code-gen-options.html

<div class="section-level-extent" id="Code-Gen-Options"> <div class="nav-panel"> <p> Next: <a href="developer-options" accesskey="n" rel="next">GCC Developer Options</a>, Previous: <a href="directory-options" accesskey="p" rel="prev">Options for Directory Search</a>, Up: <a href="invoking-gcc" accesskey="u" rel="up">GCC Command Options</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div>  <h1 class="section" id="Options-for-Code-Generation-Conventions"><span>3.17 Options for Code Generation Conventions<a class="copiable-link" href="#Options-for-Code-Generation-Conventions"> ¶</a></span></h1>    <p>These machine-independent options control the interface conventions used in code generation. </p> <p>Most of them have both positive and negative forms; the negative form of <samp class="option">-ffoo</samp> is <samp class="option">-fno-foo</samp>. In the table below, only one of the forms is listed—the one that is not the default. You can figure out the other form by either removing ‘<samp class="samp">no-</samp>’ or adding it. </p> <dl class="table"> <dt>
<span><code class="code">-fstack-reuse=<var class="var">reuse-level</var></code><a class="copiable-link" href="#index-fstack_005freuse"> ¶</a></span>
</dt> <dd>
<p>This option controls stack space reuse for user declared local/auto variables and compiler generated temporaries. <var class="var">reuse_level</var> can be ‘<samp class="samp">all</samp>’, ‘<samp class="samp">named_vars</samp>’, or ‘<samp class="samp">none</samp>’. ‘<samp class="samp">all</samp>’ enables stack reuse for all local variables and temporaries, ‘<samp class="samp">named_vars</samp>’ enables the reuse only for user defined local variables with names, and ‘<samp class="samp">none</samp>’ disables stack reuse completely. The default value is ‘<samp class="samp">all</samp>’. The option is needed when the program extends the lifetime of a scoped local variable or a compiler generated temporary beyond the end point defined by the language. When a lifetime of a variable ends, and if the variable lives in memory, the optimizing compiler has the freedom to reuse its stack space with other temporaries or scoped local variables whose live range does not overlap with it. Legacy code extending local lifetime is likely to break with the stack reuse optimization. </p> <p>For example, </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">int *p;
{
  int local1;

  p = &amp;local1;
  local1 = 10;
  ....
}
{
   int local2;
   local2 = 20;
   ...
}

if (*p == 10)  // out of scope use of local1
  {

  }</pre>
</div> <p>Another example: </p>
<div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">struct A
{
    A(int k) : i(k), j(k) { }
    int i;
    int j;
};

A *ap;

void foo(const A&amp; ar)
{
   ap = &amp;ar;
}

void bar()
{
   foo(A(10)); // temp object's lifetime ends when foo returns

   {
     A a(20);
     ....
   }
   ap-&gt;i+= 10;  // ap references out of scope temp whose space
                // is reused with a. What is the value of ap-&gt;i?
}</pre>
</div> <p>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 lives in memory, the optimizing compiler has the freedom to reuse its stack space with other temporaries or scoped local variables whose live range does not overlap with it. However some of the legacy code relies on the behavior of older compilers in which temporaries’ stack space is not reused, the aggressive stack reuse can lead to runtime errors. This option is used to control the temporary stack reuse optimization. </p> </dd> <dt>
<span><code class="code">-ftrapv</code><a class="copiable-link" href="#index-ftrapv"> ¶</a></span>
</dt> <dd>
<p>This option generates traps for signed overflow on addition, subtraction, multiplication operations. The options <samp class="option">-ftrapv</samp> and <samp class="option">-fwrapv</samp> override each other, so using <samp class="option">-ftrapv</samp> <samp class="option">-fwrapv</samp> on the command-line results in <samp class="option">-fwrapv</samp> being effective. Note that only active options override, so using <samp class="option">-ftrapv</samp> <samp class="option">-fwrapv</samp> <samp class="option">-fno-wrapv</samp> on the command-line results in <samp class="option">-ftrapv</samp> being effective. </p> </dd> <dt>
<span><code class="code">-fwrapv</code><a class="copiable-link" href="#index-fwrapv"> ¶</a></span>
</dt> <dd>
<p>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. The options <samp class="option">-ftrapv</samp> and <samp class="option">-fwrapv</samp> override each other, so using <samp class="option">-ftrapv</samp> <samp class="option">-fwrapv</samp> on the command-line results in <samp class="option">-fwrapv</samp> being effective. Note that only active options override, so using <samp class="option">-ftrapv</samp> <samp class="option">-fwrapv</samp> <samp class="option">-fno-wrapv</samp> on the command-line results in <samp class="option">-ftrapv</samp> being effective. </p> </dd> <dt>
<span><code class="code">-fwrapv-pointer</code><a class="copiable-link" href="#index-fwrapv-pointer"> ¶</a></span>
</dt> <dd>
<p>This option instructs the compiler to assume that pointer arithmetic overflow on addition and subtraction wraps around using twos-complement representation. This flag disables some optimizations which assume pointer overflow is invalid. </p> </dd> <dt>
<span><code class="code">-fstrict-overflow</code><a class="copiable-link" href="#index-fstrict-overflow"> ¶</a></span>
</dt> <dd>
<p>This option implies <samp class="option">-fno-wrapv</samp> <samp class="option">-fno-wrapv-pointer</samp> and when negated implies <samp class="option">-fwrapv</samp> <samp class="option">-fwrapv-pointer</samp>. </p> </dd> <dt>
<span><code class="code">-fexceptions</code><a class="copiable-link" href="#index-fexceptions"> ¶</a></span>
</dt> <dd>
<p>Enable exception handling. Generates extra code needed to propagate exceptions. For some targets, this implies GCC generates 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 enables it by default for languages like C++ that normally require exception handling, and disables 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. </p> </dd> <dt>
<span><code class="code">-fnon-call-exceptions</code><a class="copiable-link" href="#index-fnon-call-exceptions"> ¶</a></span>
</dt> <dd>
<p>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 <em class="emph">trapping</em> instructions to throw exceptions, i.e. memory references or floating-point instructions. It does not allow exceptions to be thrown from arbitrary signal handlers such as <code class="code">SIGALRM</code>. This enables <samp class="option">-fexceptions</samp>. </p> </dd> <dt>
<span><code class="code">-fdelete-dead-exceptions</code><a class="copiable-link" href="#index-fdelete-dead-exceptions"> ¶</a></span>
</dt> <dd>
<p>Consider that instructions that may throw exceptions but don’t otherwise contribute to the execution of the program can be optimized away. This does not affect calls to functions except those with the <code class="code">pure</code> or <code class="code">const</code> attributes. This option is enabled by default for the Ada and C++ compilers, as permitted by the language specifications. Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels. </p> </dd> <dt>
<span><code class="code">-funwind-tables</code><a class="copiable-link" href="#index-funwind-tables"> ¶</a></span>
</dt> <dd>
<p>Similar to <samp class="option">-fexceptions</samp>, except that it just generates any needed static data, but does not affect the generated code in any other way. You normally do not need to enable this option; instead, a language processor that needs this handling enables it on your behalf. </p> </dd> <dt>
<span><code class="code">-fasynchronous-unwind-tables</code><a class="copiable-link" href="#index-fasynchronous-unwind-tables"> ¶</a></span>
</dt> <dd>
<p>Generate unwind table in DWARF 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). </p> </dd> <dt>
 <span><code class="code">-fno-gnu-unique</code><a class="copiable-link" href="#index-fno-gnu-unique"> ¶</a></span>
</dt> <dd>
<p>On systems with recent GNU assembler and C library, the C++ compiler uses the <code class="code">STB_GNU_UNIQUE</code> binding to make sure that definitions of template static data members and static local variables in inline functions are unique even in the presence of <code class="code">RTLD_LOCAL</code>; this is necessary to avoid problems with a library used by two different <code class="code">RTLD_LOCAL</code> plugins depending on a definition in one of them and therefore disagreeing with the other one about the binding of the symbol. But this causes <code class="code">dlclose</code> to be ignored for affected DSOs; if your program relies on reinitialization of a DSO via <code class="code">dlclose</code> and <code class="code">dlopen</code>, you can use <samp class="option">-fno-gnu-unique</samp>. </p> </dd> <dt>
<span><code class="code">-fpcc-struct-return</code><a class="copiable-link" href="#index-fpcc-struct-return"> ¶</a></span>
</dt> <dd>
<p>Return “short” <code class="code">struct</code> and <code class="code">union</code> 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). </p> <p>The precise convention for returning structures in memory depends on the target configuration macros. </p> <p>Short structures and unions are those whose size and alignment match that of some integer type. </p> <p><strong class="strong">Warning:</strong> code compiled with the <samp class="option">-fpcc-struct-return</samp> switch is not binary compatible with code compiled with the <samp class="option">-freg-struct-return</samp> switch. Use it to conform to a non-default application binary interface. </p> </dd> <dt>
<span><code class="code">-freg-struct-return</code><a class="copiable-link" href="#index-freg-struct-return"> ¶</a></span>
</dt> <dd>
<p>Return <code class="code">struct</code> and <code class="code">union</code> values in registers when possible. This is more efficient for small structures than <samp class="option">-fpcc-struct-return</samp>. </p> <p>If you specify neither <samp class="option">-fpcc-struct-return</samp> nor <samp class="option">-freg-struct-return</samp>, GCC defaults to whichever convention is standard for the target. If there is no standard convention, GCC defaults to <samp class="option">-fpcc-struct-return</samp>, 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. </p> <p><strong class="strong">Warning:</strong> code compiled with the <samp class="option">-freg-struct-return</samp> switch is not binary compatible with code compiled with the <samp class="option">-fpcc-struct-return</samp> switch. Use it to conform to a non-default application binary interface. </p> </dd> <dt>
<span><code class="code">-fshort-enums</code><a class="copiable-link" href="#index-fshort-enums"> ¶</a></span>
</dt> <dd>
<p>Allocate to an <code class="code">enum</code> type only as many bytes as it needs for the declared range of possible values. Specifically, the <code class="code">enum</code> type is equivalent to the smallest integer type that has enough room. </p> <p><strong class="strong">Warning:</strong> the <samp class="option">-fshort-enums</samp> 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. </p> </dd> <dt>
<span><code class="code">-fshort-wchar</code><a class="copiable-link" href="#index-fshort-wchar"> ¶</a></span>
</dt> <dd>
<p>Override the underlying type for <code class="code">wchar_t</code> to be <code class="code">short
unsigned int</code> instead of the default for the target. This option is useful for building programs to run under WINE. </p> <p><strong class="strong">Warning:</strong> the <samp class="option">-fshort-wchar</samp> 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. </p> </dd> <dt>
  <span><code class="code">-fcommon</code><a class="copiable-link" href="#index-fcommon"> ¶</a></span>
</dt> <dd>
<p>In C code, this option controls the placement of global variables defined without an initializer, known as <em class="dfn">tentative definitions</em> in the C standard. Tentative definitions are distinct from declarations of a variable with the <code class="code">extern</code> keyword, which do not allocate storage. </p> <p>The default is <samp class="option">-fno-common</samp>, which specifies that the compiler places uninitialized global variables in the BSS section of the object file. This inhibits the merging of tentative definitions by the linker so you get a multiple-definition error if the same variable is accidentally defined in more than one compilation unit. </p> <p>The <samp class="option">-fcommon</samp> places uninitialized global variables in a common block. This allows the linker to resolve all tentative definitions of the same variable in different compilation units to the same object, or to a non-tentative definition. This behavior is inconsistent with C++, and on many targets implies a speed and code size penalty on global variable references. It is mainly useful to enable legacy code to link without errors. </p> </dd> <dt>
 <span><code class="code">-fno-ident</code><a class="copiable-link" href="#index-fno-ident"> ¶</a></span>
</dt> <dd>
<p>Ignore the <code class="code">#ident</code> directive. </p> </dd> <dt>
<span><code class="code">-finhibit-size-directive</code><a class="copiable-link" href="#index-finhibit-size-directive"> ¶</a></span>
</dt> <dd>
<p>Don’t output a <code class="code">.size</code> 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 <samp class="file">crtstuff.c</samp>; you should not need to use it for anything else. </p> </dd> <dt>
<span><code class="code">-fverbose-asm</code><a class="copiable-link" href="#index-fverbose-asm"> ¶</a></span>
</dt> <dd>
<p>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). </p> <p><samp class="option">-fno-verbose-asm</samp>, the default, causes the extra information to be omitted and is useful when comparing two assembler files. </p> <p>The added comments include: </p> <ul class="itemize mark-bullet"> <li>information on the compiler version and command-line options, </li>
<li>the source code lines associated with the assembly instructions, in the form FILENAME:LINENUMBER:CONTENT OF LINE, </li>
<li>hints on which high-level expressions correspond to the various assembly instruction operands. </li>
</ul> <p>For example, given this C source file: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">int test (int n)
{
  int i;
  int total = 0;

  for (i = 0; i &lt; n; i++)
    total += i * i;

  return total;
}</pre>
</div> <p>compiling to (x86_64) assembly via <samp class="option">-S</samp> and emitting the result direct to stdout via <samp class="option">-o</samp> <samp class="option">-</samp> </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">gcc -S test.c -fverbose-asm -Os -o -</pre>
</div> <p>gives output similar to this: </p> <div class="example smallexample"> <pre class="example-preformatted" data-language="cpp">.file	"test.c"
# GNU C11 (GCC) version 7.0.0 20160809 (experimental) (x86_64-pc-linux-gnu)
  [...snip...]
# options passed:
  [...snip...]

	.text
	.globl	test
	.type	test, @function
test:
.LFB0:
	.cfi_startproc
# test.c:4:   int total = 0;
	xorl	%eax, %eax	# &lt;retval&gt;
# test.c:6:   for (i = 0; i &lt; n; i++)
	xorl	%edx, %edx	# i
.L2:
# test.c:6:   for (i = 0; i &lt; n; i++)
	cmpl	%edi, %edx	# n, i
	jge	.L5	#,
# test.c:7:     total += i * i;
	movl	%edx, %ecx	# i, tmp92
	imull	%edx, %ecx	# i, tmp92
# test.c:6:   for (i = 0; i &lt; n; i++)
	incl	%edx	# i
# test.c:7:     total += i * i;
	addl	%ecx, %eax	# tmp92, &lt;retval&gt;
	jmp	.L2	#
.L5:
# test.c:10: }
	ret
	.cfi_endproc
.LFE0:
	.size	test, .-test
	.ident	"GCC: (GNU) 7.0.0 20160809 (experimental)"
	.section	.note.GNU-stack,"",@progbits</pre>
</div> <p>The comments are intended for humans rather than machines and hence the precise format of the comments is subject to change. </p> </dd> <dt>
<span><code class="code">-frecord-gcc-switches</code><a class="copiable-link" href="#index-frecord-gcc-switches"> ¶</a></span>
</dt> <dd>
<p>This switch causes the command line 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 <samp class="option">-fverbose-asm</samp> switch, but that switch only records information in the assembler output file as comments, so it never reaches the object file. See also <samp class="option">-grecord-gcc-switches</samp> for another way of storing compiler options into the object file. </p> </dd> <dt>
  <span><code class="code">-fpic</code><a class="copiable-link" href="#index-fpic"> ¶</a></span>
</dt> <dd>
<p>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 <samp class="option">-fpic</samp> does not work; in that case, recompile with <samp class="option">-fPIC</samp> instead. (These maximums are 8k on the SPARC, 28k on AArch64 and 32k on the m68k and RS/6000. The x86 has no such limit.) </p> <p>Position-independent code requires special support, and therefore works only on certain machines. For the x86, GCC supports PIC for System V but not for the Sun 386i. Code generated for the IBM RS/6000 is always position-independent. </p> <p>When this flag is set, the macros <code class="code">__pic__</code> and <code class="code">__PIC__</code> are defined to 1. </p> </dd> <dt>
<span><code class="code">-fPIC</code><a class="copiable-link" href="#index-fPIC"> ¶</a></span>
</dt> <dd>
<p>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 AArch64, m68k, PowerPC and SPARC. </p> <p>Position-independent code requires special support, and therefore works only on certain machines. </p> <p>When this flag is set, the macros <code class="code">__pic__</code> and <code class="code">__PIC__</code> are defined to 2. </p> </dd> <dt>
 <span><code class="code">-fpie</code><a class="copiable-link" href="#index-fpie"> ¶</a></span>
</dt> <dt><code class="code">-fPIE</code></dt> <dd>
<p>These options are similar to <samp class="option">-fpic</samp> and <samp class="option">-fPIC</samp>, but the generated position-independent code can be only linked into executables. Usually these options are used to compile code that will be linked using the <samp class="option">-pie</samp> GCC option. </p> <p><samp class="option">-fpie</samp> and <samp class="option">-fPIE</samp> both define the macros <code class="code">__pie__</code> and <code class="code">__PIE__</code>. The macros have the value 1 for <samp class="option">-fpie</samp> and 2 for <samp class="option">-fPIE</samp>. </p> </dd> <dt>
 <span><code class="code">-fno-plt</code><a class="copiable-link" href="#index-fno-plt"> ¶</a></span>
</dt> <dd>
<p>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 exposing GOT loads to optimizations. On architectures such as 32-bit x86 where PLT stubs expect the GOT pointer in a specific register, this gives more register allocation freedom to the compiler. Lazy binding requires use of the PLT; with <samp class="option">-fno-plt</samp> all external symbols are resolved at load time. </p> <p>Alternatively, the function attribute <code class="code">noplt</code> can be used to avoid calls through the PLT for specific external functions. </p> <p>In position-dependent code, a few targets also convert calls to functions that are marked to not use the PLT to use the GOT instead. </p> </dd> <dt>
 <span><code class="code">-fno-jump-tables</code><a class="copiable-link" href="#index-fno-jump-tables"> ¶</a></span>
</dt> <dd>
<p>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 <samp class="option">-fpic</samp> or <samp class="option">-fPIC</samp> for building code that 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. </p> </dd> <dt>
 <span><code class="code">-fno-bit-tests</code><a class="copiable-link" href="#index-fno-bit-tests"> ¶</a></span>
</dt> <dd>
<p>Do not use bit tests for switch statements even where it would be more efficient than other code generation strategies. </p> </dd> <dt>
<span><code class="code">-ffixed-<var class="var">reg</var></code><a class="copiable-link" href="#index-ffixed"> ¶</a></span>
</dt> <dd>
<p>Treat the register named <var class="var">reg</var> 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). </p> <p><var class="var">reg</var> must be the name of a register. The register names accepted are machine-specific and are defined in the <code class="code">REGISTER_NAMES</code> macro in the machine description macro file. </p> <p>This flag does not have a negative form, because it specifies a three-way choice. </p> </dd> <dt>
<span><code class="code">-fcall-used-<var class="var">reg</var></code><a class="copiable-link" href="#index-fcall-used"> ¶</a></span>
</dt> <dd>
<p>Treat the register named <var class="var">reg</var> 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 do not save and restore the register <var class="var">reg</var>. </p> <p>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 in the machine’s execution model produces disastrous results. </p> <p>This flag does not have a negative form, because it specifies a three-way choice. </p> </dd> <dt>
<span><code class="code">-fcall-saved-<var class="var">reg</var></code><a class="copiable-link" href="#index-fcall-saved"> ¶</a></span>
</dt> <dd>
<p>Treat the register named <var class="var">reg</var> 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 save and restore the register <var class="var">reg</var> if they use it. </p> <p>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 in the machine’s execution model produces disastrous results. </p> <p>A different sort of disaster results from the use of this flag for a register in which function values may be returned. </p> <p>This flag does not have a negative form, because it specifies a three-way choice. </p> </dd> <dt>
<span><code class="code">-fpack-struct[=<var class="var">n</var>]</code><a class="copiable-link" href="#index-fpack-struct"> ¶</a></span>
</dt> <dd>
<p>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 are output potentially unaligned at the next fitting location. </p> <p><strong class="strong">Warning:</strong> the <samp class="option">-fpack-struct</samp> 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. </p> </dd> <dt>
<span><code class="code">-fleading-underscore</code><a class="copiable-link" href="#index-fleading-underscore"> ¶</a></span>
</dt> <dd>
<p>This option and its counterpart, <samp class="option">-fno-leading-underscore</samp>, forcibly change the way C symbols are represented in the object file. One use is to help link with legacy assembly code. </p> <p><strong class="strong">Warning:</strong> the <samp class="option">-fleading-underscore</samp> 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. </p> </dd> <dt>
<span><code class="code">-ftls-model=<var class="var">model</var></code><a class="copiable-link" href="#index-ftls-model"> ¶</a></span>
</dt> <dd>
<p>Alter the thread-local storage model to be used (see <a class="pxref" href="thread-local">Thread-Local Storage</a>). The <var class="var">model</var> argument should be one of ‘<samp class="samp">global-dynamic</samp>’, ‘<samp class="samp">local-dynamic</samp>’, ‘<samp class="samp">initial-exec</samp>’ or ‘<samp class="samp">local-exec</samp>’. Note that the choice is subject to optimization: the compiler may use a more efficient model for symbols not visible outside of the translation unit, or if <samp class="option">-fpic</samp> is not given on the command line. </p> <p>The default without <samp class="option">-fpic</samp> is ‘<samp class="samp">initial-exec</samp>’; with <samp class="option">-fpic</samp> the default is ‘<samp class="samp">global-dynamic</samp>’. </p> </dd> <dt>
<span><code class="code">-ftrampolines</code><a class="copiable-link" href="#index-ftrampolines"> ¶</a></span>
</dt> <dd>
<p>For targets that normally need trampolines for nested functions, always generate them instead of using descriptors. Otherwise, for targets that do not need them, like for example HP-PA or IA-64, do nothing. </p> <p>A trampoline is a small piece of code that is created at run time on the stack when the address of a nested function is taken, and is used to call the nested function indirectly. Therefore, it requires the stack to be made executable in order for the program to work properly. </p> <p><samp class="option">-fno-trampolines</samp> is enabled by default on a language by language basis to let the compiler avoid generating them, if it computes that this is safe, and replace them with descriptors. Descriptors are made up of data only, but the generated code must be prepared to deal with them. As of this writing, <samp class="option">-fno-trampolines</samp> is enabled by default only for Ada. </p> <p>Moreover, code compiled with <samp class="option">-ftrampolines</samp> and code compiled with <samp class="option">-fno-trampolines</samp> are not binary compatible if nested functions are present. This option must therefore be used on a program-wide basis and be manipulated with extreme care. </p> <p>For languages other than Ada, the <code class="code">-ftrampolines</code> and <code class="code">-fno-trampolines</code> options currently have no effect, and trampolines are always generated on platforms that need them for nested functions. </p> </dd> <dt>
<span><code class="code">-fvisibility=<span class="r">[</span>default<span class="r">|</span>internal<span class="r">|</span>hidden<span class="r">|</span>protected<span class="r">]</span></code><a class="copiable-link" href="#index-fvisibility"> ¶</a></span>
</dt> <dd>
<p>Set the default ELF image symbol visibility to the specified option—all symbols are 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 <strong class="strong">strongly</strong> recommended that you use this in any shared objects you distribute. </p> <p>Despite the nomenclature, ‘<samp class="samp">default</samp>’ always means public; i.e., available to be linked against from outside the shared object. ‘<samp class="samp">protected</samp>’ and ‘<samp class="samp">internal</samp>’ are pretty useless in real-world usage so the only other commonly used option is ‘<samp class="samp">hidden</samp>’. The default if <samp class="option">-fvisibility</samp> isn’t specified is ‘<samp class="samp">default</samp>’, i.e., make every symbol public. </p> <p>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 <a class="uref" href="https://www.akkadia.org/drepper/">https://www.akkadia.org/drepper/</a>)—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 DLLs on Windows and with <samp class="option">-fvisibility=hidden</samp> and <code class="code">__attribute__ ((visibility("default")))</code> instead of <code class="code">__declspec(dllexport)</code> you get almost identical semantics with identical syntax. This is a great boon to those working with cross-platform projects. </p> <p>For those adding visibility support to existing code, you may find <code class="code">#pragma GCC visibility</code> of use. This works by you enclosing the declarations you wish to set visibility for with (for example) <code class="code">#pragma GCC visibility push(hidden)</code> and <code class="code">#pragma GCC visibility pop</code>. Bear in mind that symbol visibility should be viewed <strong class="strong">as part of the API interface contract</strong> and thus all new code should always specify visibility when it is not the default; i.e., declarations only for use within the local DSO should <strong class="strong">always</strong> 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, <code class="code">operator new</code> and <code class="code">operator delete</code> must always be of default visibility. </p> <p>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 <code class="code">#pragma GCC visibility push(default)</code> before including any such headers. </p> <p><code class="code">extern</code> declarations are not affected by <samp class="option">-fvisibility</samp>, so a lot of code can be recompiled with <samp class="option">-fvisibility=hidden</samp> with no modifications. However, this means that calls to <code class="code">extern</code> functions with no explicit visibility use the PLT, so it is more effective to use <code class="code">__attribute ((visibility))</code> and/or <code class="code">#pragma GCC visibility</code> to tell the compiler which <code class="code">extern</code> declarations should be treated as hidden. </p> <p>Note that <samp class="option">-fvisibility</samp> does affect C++ vague linkage entities. This means that, for instance, an exception class that is be thrown between DSOs must be explicitly marked with default visibility so that the ‘<samp class="samp">type_info</samp>’ nodes are unified between the DSOs. </p> <p>An overview of these techniques, their benefits and how to use them is at <a class="uref" href="https://gcc.gnu.org/wiki/Visibility">https://gcc.gnu.org/wiki/Visibility</a>. </p> </dd> <dt>
<span><code class="code">-fstrict-volatile-bitfields</code><a class="copiable-link" href="#index-fstrict-volatile-bitfields"> ¶</a></span>
</dt> <dd>
<p>This option should be used if accesses to volatile bit-fields (or other structure fields, although the compiler usually honors those types anyway) should use a single access of the width of the field’s type, aligned to a natural alignment if possible. For example, targets with memory-mapped peripheral registers might require all such accesses to be 16 bits wide; with this flag you can declare all peripheral bit-fields as <code class="code">unsigned short</code> (assuming short is 16 bits on these targets) to force GCC to use 16-bit accesses instead of, perhaps, a more efficient 32-bit access. </p> <p>If this option is disabled, the compiler uses the most efficient instruction. In the previous example, that might be a 32-bit load instruction, even though that accesses bytes that do not contain any portion of the bit-field, or memory-mapped registers unrelated to the one being updated. </p> <p>In some cases, such as when the <code class="code">packed</code> attribute is applied to a structure field, it may not be possible to access the field with a single read or write that is correctly aligned for the target machine. In this case GCC falls back to generating multiple accesses rather than code that will fault or truncate the result at run time. </p> <p>Note: Due to restrictions of the C/C++11 memory model, write accesses are not allowed to touch non bit-field members. It is therefore recommended to define all bits of the field’s type as bit-field members. </p> <p>The default value of this option is determined by the application binary interface for the target processor. </p> </dd> <dt>
<span><code class="code">-fsync-libcalls</code><a class="copiable-link" href="#index-fsync-libcalls"> ¶</a></span>
</dt> <dd>
<p>This option controls whether any out-of-line instance of the <code class="code">__sync</code> family of functions may be used to implement the C++11 <code class="code">__atomic</code> family of functions. </p> <p>The default value of this option is enabled, thus the only useful form of the option is <samp class="option">-fno-sync-libcalls</samp>. This option is used in the implementation of the <samp class="file">libatomic</samp> runtime library. </p> </dd> </dl> </div>  <div class="nav-panel"> <p> Next: <a href="developer-options">GCC Developer Options</a>, Previous: <a href="directory-options">Options for Directory Search</a>, Up: <a href="invoking-gcc">GCC Command Options</a> [<a href="index#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="indices" title="Index" rel="index">Index</a>]</p> </div><div class="_attribution">
  <p class="_attribution-p">
    &copy; Free Software Foundation<br>Licensed under the GNU Free Documentation License, Version 1.3.<br>
    <a href="https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Code-Gen-Options.html" class="_attribution-link">https://gcc.gnu.org/onlinedocs/gcc-13.1.0/gcc/Code-Gen-Options.html</a>
  </p>
</div>