| <html lang="en"> | |
| <head> | |
| <title>Code Gen Options - Using the GNU Compiler Collection (GCC)</title> | |
| <meta http-equiv="Content-Type" content="text/html"> | |
| <meta name="description" content="Using the GNU Compiler Collection (GCC)"> | |
| <meta name="generator" content="makeinfo 4.13"> | |
| <link title="Top" rel="start" href="index.html#Top"> | |
| <link rel="up" href="Invoking-GCC.html#Invoking-GCC" title="Invoking GCC"> | |
| <link rel="prev" href="Submodel-Options.html#Submodel-Options" title="Submodel Options"> | |
| <link rel="next" href="Environment-Variables.html#Environment-Variables" title="Environment Variables"> | |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> | |
| <!-- | |
| Copyright (C) 1988-2013 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.3 or | |
| any later version published by the Free Software Foundation; with the | |
| Invariant Sections being ``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 section entitled | |
| ``GNU Free Documentation License''. | |
| (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.--> | |
| <meta http-equiv="Content-Style-Type" content="text/css"> | |
| <style type="text/css"><!-- | |
| pre.display { font-family:inherit } | |
| pre.format { font-family:inherit } | |
| pre.smalldisplay { font-family:inherit; font-size:smaller } | |
| pre.smallformat { font-family:inherit; font-size:smaller } | |
| pre.smallexample { font-size:smaller } | |
| pre.smalllisp { font-size:smaller } | |
| span.sc { font-variant:small-caps } | |
| span.roman { font-family:serif; font-weight:normal; } | |
| span.sansserif { font-family:sans-serif; font-weight:normal; } | |
| --></style> | |
| </head> | |
| <body> | |
| <div class="node"> | |
| <a name="Code-Gen-Options"></a> | |
| <p> | |
| Next: <a rel="next" accesskey="n" href="Environment-Variables.html#Environment-Variables">Environment Variables</a>, | |
| Previous: <a rel="previous" accesskey="p" href="Submodel-Options.html#Submodel-Options">Submodel Options</a>, | |
| Up: <a rel="up" accesskey="u" href="Invoking-GCC.html#Invoking-GCC">Invoking GCC</a> | |
| <hr> | |
| </div> | |
| <h3 class="section">3.18 Options for Code Generation Conventions</h3> | |
| <p><a name="index-code-generation-conventions-2323"></a><a name="index-options_002c-code-generation-2324"></a><a name="index-run_002dtime-options-2325"></a> | |
| These machine-independent options control the interface conventions | |
| used in code generation. | |
| <p>Most of them have both positive and negative forms; the negative form | |
| of <samp><span class="option">-ffoo</span></samp> is <samp><span class="option">-fno-foo</span></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><span class="samp">no-</span></samp>’ or adding | |
| it. | |
| <dl> | |
| <dt><code>-fbounds-check</code><dd><a name="index-fbounds_002dcheck-2326"></a>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. | |
| <br><dt><code>-fstack-reuse=</code><var>reuse-level</var><dd><a name="index-fstack_005freuse-2327"></a>This option controls stack space reuse for user declared local/auto variables | |
| and compiler generated temporaries. <var>reuse_level</var> can be ‘<samp><span class="samp">all</span></samp>’, | |
| ‘<samp><span class="samp">named_vars</span></samp>’, or ‘<samp><span class="samp">none</span></samp>’. ‘<samp><span class="samp">all</span></samp>’ enables stack reuse for all | |
| local variables and temporaries, ‘<samp><span class="samp">named_vars</span></samp>’ enables the reuse only for | |
| user defined local variables with names, and ‘<samp><span class="samp">none</span></samp>’ disables stack reuse | |
| completely. The default value is ‘<samp><span class="samp">all</span></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 will likely to break with the stack reuse optimization. | |
| <p>For example, | |
| <pre class="smallexample"> int *p; | |
| { | |
| int local1; | |
| p = &local1; | |
| local1 = 10; | |
| .... | |
| } | |
| { | |
| int local2; | |
| local2 = 20; | |
| ... | |
| } | |
| if (*p == 10) // out of scope use of local1 | |
| { | |
| } | |
| </pre> | |
| <p>Another example: | |
| <pre class="smallexample"> | |
| 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? | |
| } | |
| </pre> | |
| <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. | |
| <br><dt><code>-ftrapv</code><dd><a name="index-ftrapv-2328"></a>This option generates traps for signed overflow on addition, subtraction, | |
| multiplication operations. | |
| <br><dt><code>-fwrapv</code><dd><a name="index-fwrapv-2329"></a>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. | |
| <br><dt><code>-fexceptions</code><dd><a name="index-fexceptions-2330"></a>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. | |
| <br><dt><code>-fnon-call-exceptions</code><dd><a name="index-fnon_002dcall_002dexceptions-2331"></a>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>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>SIGALRM</code>. | |
| <br><dt><code>-fdelete-dead-exceptions</code><dd><a name="index-fdelete_002ddead_002dexceptions-2332"></a>Consider that instructions that may throw exceptions but don't otherwise | |
| contribute to the execution of the program can be optimized away. | |
| This option is enabled by default for the Ada front end, as permitted by | |
| the Ada language specification. | |
| Optimization passes that cause dead exceptions to be removed are enabled independently at different optimization levels. | |
| <br><dt><code>-funwind-tables</code><dd><a name="index-funwind_002dtables-2333"></a>Similar to <samp><span class="option">-fexceptions</span></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. | |
| <br><dt><code>-fasynchronous-unwind-tables</code><dd><a name="index-fasynchronous_002dunwind_002dtables-2334"></a>Generate unwind table in DWARF 2 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). | |
| <br><dt><code>-fpcc-struct-return</code><dd><a name="index-fpcc_002dstruct_002dreturn-2335"></a>Return “short” <code>struct</code> and <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>The precise convention for returning structures in memory depends | |
| on the target configuration macros. | |
| <p>Short structures and unions are those whose size and alignment match | |
| that of some integer type. | |
| <p><strong>Warning:</strong> code compiled with the <samp><span class="option">-fpcc-struct-return</span></samp> | |
| switch is not binary compatible with code compiled with the | |
| <samp><span class="option">-freg-struct-return</span></samp> switch. | |
| Use it to conform to a non-default application binary interface. | |
| <br><dt><code>-freg-struct-return</code><dd><a name="index-freg_002dstruct_002dreturn-2336"></a>Return <code>struct</code> and <code>union</code> values in registers when possible. | |
| This is more efficient for small structures than | |
| <samp><span class="option">-fpcc-struct-return</span></samp>. | |
| <p>If you specify neither <samp><span class="option">-fpcc-struct-return</span></samp> nor | |
| <samp><span class="option">-freg-struct-return</span></samp>, GCC defaults to whichever convention is | |
| standard for the target. If there is no standard convention, GCC | |
| defaults to <samp><span class="option">-fpcc-struct-return</span></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><strong>Warning:</strong> code compiled with the <samp><span class="option">-freg-struct-return</span></samp> | |
| switch is not binary compatible with code compiled with the | |
| <samp><span class="option">-fpcc-struct-return</span></samp> switch. | |
| Use it to conform to a non-default application binary interface. | |
| <br><dt><code>-fshort-enums</code><dd><a name="index-fshort_002denums-2337"></a>Allocate to an <code>enum</code> type only as many bytes as it needs for the | |
| declared range of possible values. Specifically, the <code>enum</code> type | |
| is equivalent to the smallest integer type that has enough room. | |
| <p><strong>Warning:</strong> the <samp><span class="option">-fshort-enums</span></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. | |
| <br><dt><code>-fshort-double</code><dd><a name="index-fshort_002ddouble-2338"></a>Use the same size for <code>double</code> as for <code>float</code>. | |
| <p><strong>Warning:</strong> the <samp><span class="option">-fshort-double</span></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. | |
| <br><dt><code>-fshort-wchar</code><dd><a name="index-fshort_002dwchar-2339"></a>Override the underlying type for ‘<samp><span class="samp">wchar_t</span></samp>’ to be ‘<samp><span class="samp">short | |
| unsigned int</span></samp>’ instead of the default for the target. This option is | |
| useful for building programs to run under WINE. | |
| <p><strong>Warning:</strong> the <samp><span class="option">-fshort-wchar</span></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. | |
| <br><dt><code>-fno-common</code><dd><a name="index-fno_002dcommon-2340"></a>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 <samp><span class="option">-fcommon</span></samp>, 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 <samp><span class="option">-fno-common</span></samp> 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 <code>extern</code>) in two different compilations, | |
| you get a multiple-definition error when you link them. | |
| In this case, you must compile with <samp><span class="option">-fcommon</span></samp> instead. | |
| Compiling with <samp><span class="option">-fno-common</span></samp> is useful on targets for which | |
| it provides better performance, or if you wish to verify that the | |
| program will work on other systems that always treat uninitialized | |
| variable declarations this way. | |
| <br><dt><code>-fno-ident</code><dd><a name="index-fno_002dident-2341"></a>Ignore the ‘<samp><span class="samp">#ident</span></samp>’ directive. | |
| <br><dt><code>-finhibit-size-directive</code><dd><a name="index-finhibit_002dsize_002ddirective-2342"></a>Don't output a <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><span class="file">crtstuff.c</span></samp>; you should not need to use it | |
| for anything else. | |
| <br><dt><code>-fverbose-asm</code><dd><a name="index-fverbose_002dasm-2343"></a>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><samp><span class="option">-fno-verbose-asm</span></samp>, the default, causes the | |
| extra information to be omitted and is useful when comparing two assembler | |
| files. | |
| <br><dt><code>-frecord-gcc-switches</code><dd><a name="index-frecord_002dgcc_002dswitches-2344"></a>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><span class="option">-fverbose-asm</span></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><span class="option">-grecord-gcc-switches</span></samp> for another | |
| way of storing compiler options into the object file. | |
| <br><dt><code>-fpic</code><dd><a name="index-fpic-2345"></a><a name="index-global-offset-table-2346"></a><a name="index-PIC-2347"></a>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><span class="option">-fpic</span></samp> does not work; in that case, recompile with <samp><span class="option">-fPIC</span></samp> | |
| instead. (These maximums are 8k on the SPARC and 32k | |
| on the m68k and RS/6000. The 386 has no such limit.) | |
| <p>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. | |
| <p>When this flag is set, the macros <code>__pic__</code> and <code>__PIC__</code> | |
| are defined to 1. | |
| <br><dt><code>-fPIC</code><dd><a name="index-fPIC-2348"></a>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. | |
| <p>Position-independent code requires special support, and therefore works | |
| only on certain machines. | |
| <p>When this flag is set, the macros <code>__pic__</code> and <code>__PIC__</code> | |
| are defined to 2. | |
| <br><dt><code>-fpie</code><dt><code>-fPIE</code><dd><a name="index-fpie-2349"></a><a name="index-fPIE-2350"></a>These options are similar to <samp><span class="option">-fpic</span></samp> and <samp><span class="option">-fPIC</span></samp>, but | |
| generated position independent code can be only linked into executables. | |
| Usually these options are used when <samp><span class="option">-pie</span></samp> GCC option is | |
| used during linking. | |
| <p><samp><span class="option">-fpie</span></samp> and <samp><span class="option">-fPIE</span></samp> both define the macros | |
| <code>__pie__</code> and <code>__PIE__</code>. The macros have the value 1 | |
| for <samp><span class="option">-fpie</span></samp> and 2 for <samp><span class="option">-fPIE</span></samp>. | |
| <br><dt><code>-fno-jump-tables</code><dd><a name="index-fno_002djump_002dtables-2351"></a>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><span class="option">-fpic</span></samp> or <samp><span class="option">-fPIC</span></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. | |
| <br><dt><code>-ffixed-</code><var>reg</var><dd><a name="index-ffixed-2352"></a>Treat the register named <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><var>reg</var> must be the name of a register. The register names accepted | |
| are machine-specific and are defined in the <code>REGISTER_NAMES</code> | |
| macro in the machine description macro file. | |
| <p>This flag does not have a negative form, because it specifies a | |
| three-way choice. | |
| <br><dt><code>-fcall-used-</code><var>reg</var><dd><a name="index-fcall_002dused-2353"></a>Treat the register named <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>reg</var>. | |
| <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>This flag does not have a negative form, because it specifies a | |
| three-way choice. | |
| <br><dt><code>-fcall-saved-</code><var>reg</var><dd><a name="index-fcall_002dsaved-2354"></a>Treat the register named <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>reg</var> if they use it. | |
| <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>A different sort of disaster results from the use of this flag for | |
| a register in which function values may be returned. | |
| <p>This flag does not have a negative form, because it specifies a | |
| three-way choice. | |
| <br><dt><code>-fpack-struct[=</code><var>n</var><code>]</code><dd><a name="index-fpack_002dstruct-2355"></a>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><strong>Warning:</strong> the <samp><span class="option">-fpack-struct</span></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. | |
| <br><dt><code>-finstrument-functions</code><dd><a name="index-finstrument_002dfunctions-2356"></a>Generate instrumentation calls for entry and exit to functions. Just | |
| after function entry and just before function exit, the following | |
| profiling functions are called with the address of the current | |
| function and its call site. (On some platforms, | |
| <code>__builtin_return_address</code> does not work beyond the current | |
| function, so the call site information may not be available to the | |
| profiling functions otherwise.) | |
| <pre class="smallexample"> void __cyg_profile_func_enter (void *this_fn, | |
| void *call_site); | |
| void __cyg_profile_func_exit (void *this_fn, | |
| void *call_site); | |
| </pre> | |
| <p>The first argument is the address of the start of the current function, | |
| which may be looked up exactly in the symbol table. | |
| <p>This instrumentation is also done for functions expanded inline in other | |
| functions. The profiling calls 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 ‘<samp><span class="samp">extern inline</span></samp>’ in your C code, an | |
| addressable version of such functions must be provided. (This is | |
| normally the case anyway, but if you get lucky and the optimizer always | |
| expands the functions inline, you might have gotten away without | |
| providing static copies.) | |
| <p>A function may be given the attribute <code>no_instrument_function</code>, in | |
| which case this instrumentation is not 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). | |
| <br><dt><code>-finstrument-functions-exclude-file-list=</code><var>file</var><code>,</code><var>file</var><code>,...</code><dd><a name="index-finstrument_002dfunctions_002dexclude_002dfile_002dlist-2357"></a> | |
| Set the list of functions that are excluded from instrumentation (see | |
| the description of <code>-finstrument-functions</code>). If the file that | |
| contains a function definition matches with one of <var>file</var>, then | |
| that function is not instrumented. The match is done on substrings: | |
| if the <var>file</var> parameter is a substring of the file name, it is | |
| considered to be a match. | |
| <p>For example: | |
| <pre class="smallexample"> -finstrument-functions-exclude-file-list=/bits/stl,include/sys | |
| </pre> | |
| <p class="noindent">excludes any inline function defined in files whose pathnames | |
| contain <code>/bits/stl</code> or <code>include/sys</code>. | |
| <p>If, for some reason, you want to include letter <code>','</code> in one of | |
| <var>sym</var>, write <code>'\,'</code>. For example, | |
| <code>-finstrument-functions-exclude-file-list='\,\,tmp'</code> | |
| (note the single quote surrounding the option). | |
| <br><dt><code>-finstrument-functions-exclude-function-list=</code><var>sym</var><code>,</code><var>sym</var><code>,...</code><dd><a name="index-finstrument_002dfunctions_002dexclude_002dfunction_002dlist-2358"></a> | |
| This is similar to <code>-finstrument-functions-exclude-file-list</code>, | |
| 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 <code>vector<int> blah(const vector<int> &)</code>, not the | |
| internal mangled name (e.g., <code>_Z4blahRSt6vectorIiSaIiEE</code>). The | |
| match is done on substrings: if the <var>sym</var> parameter is a substring | |
| of the function name, it is considered to be a match. For C99 and C++ | |
| extended identifiers, the function name must be given in UTF-8, not | |
| using universal character names. | |
| <br><dt><code>-fstack-check</code><dd><a name="index-fstack_002dcheck-2359"></a>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 you 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. | |
| <p>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. | |
| <p>You can additionally specify a string parameter: <code>no</code> means no | |
| checking, <code>generic</code> means force the use of old-style checking, | |
| <code>specific</code> means use the best checking method and is equivalent | |
| to bare <samp><span class="option">-fstack-check</span></samp>. | |
| <p>Old-style checking is a generic mechanism that requires no specific | |
| target support in the compiler but comes with the following drawbacks: | |
| <ol type=1 start=1> | |
| <li>Modified allocation strategy for large objects: they are always | |
| allocated dynamically if their size exceeds a fixed threshold. | |
| <li>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. | |
| <li>Inefficiency: because of both the modified allocation strategy and the | |
| generic implementation, code performance is hampered. | |
| </ol> | |
| <p>Note that old-style stack checking is also the fallback method for | |
| <code>specific</code> if no target support has been added in the compiler. | |
| <br><dt><code>-fstack-limit-register=</code><var>reg</var><dt><code>-fstack-limit-symbol=</code><var>sym</var><dt><code>-fno-stack-limit</code><dd><a name="index-fstack_002dlimit_002dregister-2360"></a><a name="index-fstack_002dlimit_002dsymbol-2361"></a><a name="index-fno_002dstack_002dlimit-2362"></a>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 a larger | |
| stack is required, a signal is raised at run time. 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. | |
| <p>For instance, if the stack starts at absolute address ‘<samp><span class="samp">0x80000000</span></samp>’ | |
| and grows downwards, you can use the flags | |
| <samp><span class="option">-fstack-limit-symbol=__stack_limit</span></samp> and | |
| <samp><span class="option">-Wl,--defsym,__stack_limit=0x7ffe0000</span></samp> to enforce a stack limit | |
| of 128KB. Note that this may only work with the GNU linker. | |
| <br><dt><code>-fsplit-stack</code><dd><a name="index-fsplit_002dstack-2363"></a>Generate code to automatically split the stack before it overflows. | |
| The resulting program has a discontiguous stack which can only | |
| overflow if the program is unable to allocate any more memory. This | |
| is most useful when running threaded programs, as it is no longer | |
| necessary to calculate a good stack size to use for each thread. This | |
| is currently only implemented for the i386 and x86_64 back ends running | |
| GNU/Linux. | |
| <p>When code compiled with <samp><span class="option">-fsplit-stack</span></samp> calls code compiled | |
| without <samp><span class="option">-fsplit-stack</span></samp>, there may not be much stack space | |
| available for the latter code to run. If compiling all code, | |
| including library code, with <samp><span class="option">-fsplit-stack</span></samp> is not an option, | |
| then the linker can fix up these calls so that the code compiled | |
| without <samp><span class="option">-fsplit-stack</span></samp> always has a large stack. Support for | |
| this is implemented in the gold linker in GNU binutils release 2.21 | |
| and later. | |
| <br><dt><code>-fleading-underscore</code><dd><a name="index-fleading_002dunderscore-2364"></a>This option and its counterpart, <samp><span class="option">-fno-leading-underscore</span></samp>, forcibly | |
| change the way C symbols are represented in the object file. One use | |
| is to help link with legacy assembly code. | |
| <p><strong>Warning:</strong> the <samp><span class="option">-fleading-underscore</span></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. | |
| <br><dt><code>-ftls-model=</code><var>model</var><dd><a name="index-ftls_002dmodel-2365"></a>Alter the thread-local storage model to be used (see <a href="Thread_002dLocal.html#Thread_002dLocal">Thread-Local</a>). | |
| The <var>model</var> argument should be one of <code>global-dynamic</code>, | |
| <code>local-dynamic</code>, <code>initial-exec</code> or <code>local-exec</code>. | |
| <p>The default without <samp><span class="option">-fpic</span></samp> is <code>initial-exec</code>; with | |
| <samp><span class="option">-fpic</span></samp> the default is <code>global-dynamic</code>. | |
| <br><dt><code>-fvisibility=</code><var>default|internal|hidden|protected</var><dd><a name="index-fvisibility-2366"></a>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>strongly</strong> recommended that you use this in any shared objects | |
| you distribute. | |
| <p>Despite the nomenclature, <code>default</code> always means public; i.e., | |
| available to be linked against from outside the shared object. | |
| <code>protected</code> and <code>internal</code> are pretty useless in real-world | |
| usage so the only other commonly used option is <code>hidden</code>. | |
| The default if <samp><span class="option">-fvisibility</span></samp> isn't specified is | |
| <code>default</code>, i.e., make every | |
| symbol public—this causes the same behavior as previous versions of | |
| GCC. | |
| <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 href="http://people.redhat.com/~drepper/">http://people.redhat.com/~drepper/</a><!-- /@w -->)—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><span class="option">-fvisibility=hidden</span></samp> | |
| and <code>__attribute__ ((visibility("default")))</code> instead of | |
| <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>For those adding visibility support to existing code, you may find | |
| ‘<samp><span class="samp">#pragma GCC visibility</span></samp>’ of use. This works by you enclosing | |
| the declarations you wish to set visibility for with (for example) | |
| ‘<samp><span class="samp">#pragma GCC visibility push(hidden)</span></samp>’ and | |
| ‘<samp><span class="samp">#pragma GCC visibility pop</span></samp>’. | |
| Bear in mind that symbol visibility should be viewed <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>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>operator new</code> and | |
| <code>operator delete</code> must always be of default visibility. | |
| <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 ‘<samp><span class="samp">#pragma GCC visibility push(default)</span></samp>’ | |
| before including any such headers. | |
| <p>‘<samp><span class="samp">extern</span></samp>’ declarations are not affected by <samp><span class="option">-fvisibility</span></samp>, so | |
| a lot of code can be recompiled with <samp><span class="option">-fvisibility=hidden</span></samp> with | |
| no modifications. However, this means that calls to <code>extern</code> | |
| functions with no explicit visibility use the PLT, so it is more | |
| effective to use <code>__attribute ((visibility))</code> and/or | |
| <code>#pragma GCC visibility</code> to tell the compiler which <code>extern</code> | |
| declarations should be treated as hidden. | |
| <p>Note that <samp><span class="option">-fvisibility</span></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><span class="samp">type_info</span></samp>’ nodes are unified between | |
| the DSOs. | |
| <p>An overview of these techniques, their benefits and how to use them | |
| is at <a href="http://gcc.gnu.org/wiki/Visibility">http://gcc.gnu.org/wiki/Visibility</a>. | |
| <br><dt><code>-fstrict-volatile-bitfields</code><dd><a name="index-fstrict_002dvolatile_002dbitfields-2367"></a>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>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>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>If the target requires strict alignment, and honoring the field | |
| type would require violating this alignment, a warning is issued. | |
| If the field has <code>packed</code> attribute, the access is done without | |
| honoring the field type. If the field doesn't have <code>packed</code> | |
| attribute, the access is done honoring the field type. In both cases, | |
| GCC assumes that the user knows something about the target hardware | |
| that it is unaware of. | |
| <p>The default value of this option is determined by the application binary | |
| interface for the target processor. | |
| <br><dt><code>-fsync-libcalls</code><dd><a name="index-fsync_002dlibcalls-2368"></a>This option controls whether any out-of-line instance of the <code>__sync</code> | |
| family of functions may be used to implement the C++11 <code>__atomic</code> | |
| family of functions. | |
| <p>The default value of this option is enabled, thus the only useful form | |
| of the option is <samp><span class="option">-fno-sync-libcalls</span></samp>. This option is used in | |
| the implementation of the <samp><span class="file">libatomic</span></samp> runtime library. | |
| </dl> | |
| <!-- man end --> | |
| </body></html> | |