1<html lang="en"> 2<head> 3<title>Code Gen Options - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Invoking-GCC.html#Invoking-GCC" title="Invoking GCC"> 9<link rel="prev" href="Submodel-Options.html#Submodel-Options" title="Submodel Options"> 10<link rel="next" href="Environment-Variables.html#Environment-Variables" title="Environment Variables"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 152010 Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Funding Free Software'', the Front-Cover 21Texts being (a) (see below), and with the Back-Cover Texts being (b) 22(see below). A copy of the license is included in the section entitled 23``GNU Free Documentation License''. 24 25(a) The FSF's Front-Cover Text is: 26 27 A GNU Manual 28 29(b) The FSF's Back-Cover Text is: 30 31 You have freedom to copy and modify this GNU Manual, like GNU 32 software. Copies published by the Free Software Foundation raise 33 funds for GNU development.--> 34<meta http-equiv="Content-Style-Type" content="text/css"> 35<style type="text/css"><!-- 36 pre.display { font-family:inherit } 37 pre.format { font-family:inherit } 38 pre.smalldisplay { font-family:inherit; font-size:smaller } 39 pre.smallformat { font-family:inherit; font-size:smaller } 40 pre.smallexample { font-size:smaller } 41 pre.smalllisp { font-size:smaller } 42 span.sc { font-variant:small-caps } 43 span.roman { font-family:serif; font-weight:normal; } 44 span.sansserif { font-family:sans-serif; font-weight:normal; } 45--></style> 46<link rel="stylesheet" type="text/css" href="../cs.css"> 47</head> 48<body> 49<div class="node"> 50<a name="Code-Gen-Options"></a> 51<p> 52Next: <a rel="next" accesskey="n" href="Environment-Variables.html#Environment-Variables">Environment Variables</a>, 53Previous: <a rel="previous" accesskey="p" href="Submodel-Options.html#Submodel-Options">Submodel Options</a>, 54Up: <a rel="up" accesskey="u" href="Invoking-GCC.html#Invoking-GCC">Invoking GCC</a> 55<hr> 56</div> 57 58<h3 class="section">3.18 Options for Code Generation Conventions</h3> 59 60<p><a name="index-code-generation-conventions-2164"></a><a name="index-options_002c-code-generation-2165"></a><a name="index-run_002dtime-options-2166"></a> 61These machine-independent options control the interface conventions 62used in code generation. 63 64 <p>Most of them have both positive and negative forms; the negative form 65of <samp><span class="option">-ffoo</span></samp> would be <samp><span class="option">-fno-foo</span></samp>. In the table below, only 66one of the forms is listed—the one which is not the default. You 67can figure out the other form by either removing ‘<samp><span class="samp">no-</span></samp>’ or adding 68it. 69 70 <dl> 71<dt><code>-fbounds-check</code><dd><a name="index-fbounds_002dcheck-2167"></a>For front-ends that support it, generate additional code to check that 72indices used to access arrays are within the declared range. This is 73currently only supported by the Java and Fortran front-ends, where 74this option defaults to true and false respectively. 75 76 <br><dt><code>-ftrapv</code><dd><a name="index-ftrapv-2168"></a>This option generates traps for signed overflow on addition, subtraction, 77multiplication operations. 78 79 <br><dt><code>-fwrapv</code><dd><a name="index-fwrapv-2169"></a>This option instructs the compiler to assume that signed arithmetic 80overflow of addition, subtraction and multiplication wraps around 81using twos-complement representation. This flag enables some optimizations 82and disables others. This option is enabled by default for the Java 83front-end, as required by the Java language specification. 84 85 <br><dt><code>-fexceptions</code><dd><a name="index-fexceptions-2170"></a>Enable exception handling. Generates extra code needed to propagate 86exceptions. For some targets, this implies GCC will generate frame 87unwind information for all functions, which can produce significant data 88size overhead, although it does not affect execution. If you do not 89specify this option, GCC will enable it by default for languages like 90C++ which normally require exception handling, and disable it for 91languages like C that do not normally require it. However, you may need 92to enable this option when compiling C code that needs to interoperate 93properly with exception handlers written in C++. You may also wish to 94disable this option if you are compiling older C++ programs that don't 95use exception handling. 96 97 <br><dt><code>-fnon-call-exceptions</code><dd><a name="index-fnon_002dcall_002dexceptions-2171"></a>Generate code that allows trapping instructions to throw exceptions. 98Note that this requires platform-specific runtime support that does 99not exist everywhere. Moreover, it only allows <em>trapping</em> 100instructions to throw exceptions, i.e. memory references or floating 101point instructions. It does not allow exceptions to be thrown from 102arbitrary signal handlers such as <code>SIGALRM</code>. 103 104 <br><dt><code>-funwind-tables</code><dd><a name="index-funwind_002dtables-2172"></a>Similar to <samp><span class="option">-fexceptions</span></samp>, except that it will just generate any needed 105static data, but will not affect the generated code in any other way. 106You will normally not enable this option; instead, a language processor 107that needs this handling would enable it on your behalf. 108 109 <br><dt><code>-fasynchronous-unwind-tables</code><dd><a name="index-fasynchronous_002dunwind_002dtables-2173"></a>Generate unwind table in dwarf2 format, if supported by target machine. The 110table is exact at each instruction boundary, so it can be used for stack 111unwinding from asynchronous events (such as debugger or garbage collector). 112 113 <br><dt><code>-fpcc-struct-return</code><dd><a name="index-fpcc_002dstruct_002dreturn-2174"></a>Return “short” <code>struct</code> and <code>union</code> values in memory like 114longer ones, rather than in registers. This convention is less 115efficient, but it has the advantage of allowing intercallability between 116GCC-compiled files and files compiled with other compilers, particularly 117the Portable C Compiler (pcc). 118 119 <p>The precise convention for returning structures in memory depends 120on the target configuration macros. 121 122 <p>Short structures and unions are those whose size and alignment match 123that of some integer type. 124 125 <p><strong>Warning:</strong> code compiled with the <samp><span class="option">-fpcc-struct-return</span></samp> 126switch is not binary compatible with code compiled with the 127<samp><span class="option">-freg-struct-return</span></samp> switch. 128Use it to conform to a non-default application binary interface. 129 130 <br><dt><code>-freg-struct-return</code><dd><a name="index-freg_002dstruct_002dreturn-2175"></a>Return <code>struct</code> and <code>union</code> values in registers when possible. 131This is more efficient for small structures than 132<samp><span class="option">-fpcc-struct-return</span></samp>. 133 134 <p>If you specify neither <samp><span class="option">-fpcc-struct-return</span></samp> nor 135<samp><span class="option">-freg-struct-return</span></samp>, GCC defaults to whichever convention is 136standard for the target. If there is no standard convention, GCC 137defaults to <samp><span class="option">-fpcc-struct-return</span></samp>, except on targets where GCC is 138the principal compiler. In those cases, we can choose the standard, and 139we chose the more efficient register return alternative. 140 141 <p><strong>Warning:</strong> code compiled with the <samp><span class="option">-freg-struct-return</span></samp> 142switch is not binary compatible with code compiled with the 143<samp><span class="option">-fpcc-struct-return</span></samp> switch. 144Use it to conform to a non-default application binary interface. 145 146 <br><dt><code>-fshort-enums</code><dd><a name="index-fshort_002denums-2176"></a>Allocate to an <code>enum</code> type only as many bytes as it needs for the 147declared range of possible values. Specifically, the <code>enum</code> type 148will be equivalent to the smallest integer type which has enough room. 149 150 <p><strong>Warning:</strong> the <samp><span class="option">-fshort-enums</span></samp> switch causes GCC to generate 151code that is not binary compatible with code generated without that switch. 152Use it to conform to a non-default application binary interface. 153 154 <br><dt><code>-fshort-double</code><dd><a name="index-fshort_002ddouble-2177"></a>Use the same size for <code>double</code> as for <code>float</code>. 155 156 <p><strong>Warning:</strong> the <samp><span class="option">-fshort-double</span></samp> switch causes GCC to generate 157code that is not binary compatible with code generated without that switch. 158Use it to conform to a non-default application binary interface. 159 160 <br><dt><code>-fshort-wchar</code><dd><a name="index-fshort_002dwchar-2178"></a>Override the underlying type for ‘<samp><span class="samp">wchar_t</span></samp>’ to be ‘<samp><span class="samp">short 161unsigned int</span></samp>’ instead of the default for the target. This option is 162useful for building programs to run under WINE. 163 164 <p><strong>Warning:</strong> the <samp><span class="option">-fshort-wchar</span></samp> switch causes GCC to generate 165code that is not binary compatible with code generated without that switch. 166Use it to conform to a non-default application binary interface. 167 168 <br><dt><code>-fno-common</code><dd><a name="index-fno_002dcommon-2179"></a>In C code, controls the placement of uninitialized global variables. 169Unix C compilers have traditionally permitted multiple definitions of 170such variables in different compilation units by placing the variables 171in a common block. 172This is the behavior specified by <samp><span class="option">-fcommon</span></samp>, and is the default 173for GCC on most targets. 174On the other hand, this behavior is not required by ISO C, and on some 175targets may carry a speed or code size penalty on variable references. 176The <samp><span class="option">-fno-common</span></samp> option specifies that the compiler should place 177uninitialized global variables in the data section of the object file, 178rather than generating them as common blocks. 179This has the effect that if the same variable is declared 180(without <code>extern</code>) in two different compilations, 181you will get a multiple-definition error when you link them. 182In this case, you must compile with <samp><span class="option">-fcommon</span></samp> instead. 183Compiling with <samp><span class="option">-fno-common</span></samp> is useful on targets for which 184it provides better performance, or if you wish to verify that the 185program will work on other systems which always treat uninitialized 186variable declarations this way. 187 188 <br><dt><code>-fno-ident</code><dd><a name="index-fno_002dident-2180"></a>Ignore the ‘<samp><span class="samp">#ident</span></samp>’ directive. 189 190 <br><dt><code>-finhibit-size-directive</code><dd><a name="index-finhibit_002dsize_002ddirective-2181"></a>Don't output a <code>.size</code> assembler directive, or anything else that 191would cause trouble if the function is split in the middle, and the 192two halves are placed at locations far apart in memory. This option is 193used when compiling <samp><span class="file">crtstuff.c</span></samp>; you should not need to use it 194for anything else. 195 196 <br><dt><code>-fverbose-asm</code><dd><a name="index-fverbose_002dasm-2182"></a>Put extra commentary information in the generated assembly code to 197make it more readable. This option is generally only of use to those 198who actually need to read the generated assembly code (perhaps while 199debugging the compiler itself). 200 201 <p><samp><span class="option">-fno-verbose-asm</span></samp>, the default, causes the 202extra information to be omitted and is useful when comparing two assembler 203files. 204 205 <br><dt><code>-frecord-gcc-switches</code><dd><a name="index-frecord_002dgcc_002dswitches-2183"></a>This switch causes the command line that was used to invoke the 206compiler to be recorded into the object file that is being created. 207This switch is only implemented on some targets and the exact format 208of the recording is target and binary file format dependent, but it 209usually takes the form of a section containing ASCII text. This 210switch is related to the <samp><span class="option">-fverbose-asm</span></samp> switch, but that 211switch only records information in the assembler output file as 212comments, so it never reaches the object file. 213 214 <br><dt><code>-fpic</code><dd><a name="index-fpic-2184"></a><a name="index-global-offset-table-2185"></a><a name="index-PIC-2186"></a>Generate position-independent code (PIC) suitable for use in a shared 215library, if supported for the target machine. Such code accesses all 216constant addresses through a global offset table (GOT). The dynamic 217loader resolves the GOT entries when the program starts (the dynamic 218loader is not part of GCC; it is part of the operating system). If 219the GOT size for the linked executable exceeds a machine-specific 220maximum size, you get an error message from the linker indicating that 221<samp><span class="option">-fpic</span></samp> does not work; in that case, recompile with <samp><span class="option">-fPIC</span></samp> 222instead. (These maximums are 8k on the SPARC and 32k 223on the m68k and RS/6000. The 386 has no such limit.) 224 225 <p>Position-independent code requires special support, and therefore works 226only on certain machines. For the 386, GCC supports PIC for System V 227but not for the Sun 386i. Code generated for the IBM RS/6000 is always 228position-independent. 229 230 <p>When this flag is set, the macros <code>__pic__</code> and <code>__PIC__</code> 231are defined to 1. 232 233 <br><dt><code>-fPIC</code><dd><a name="index-fPIC-2187"></a>If supported for the target machine, emit position-independent code, 234suitable for dynamic linking and avoiding any limit on the size of the 235global offset table. This option makes a difference on the m68k, 236PowerPC and SPARC. 237 238 <p>Position-independent code requires special support, and therefore works 239only on certain machines. 240 241 <p>When this flag is set, the macros <code>__pic__</code> and <code>__PIC__</code> 242are defined to 2. 243 244 <br><dt><code>-fpie</code><dt><code>-fPIE</code><dd><a name="index-fpie-2188"></a><a name="index-fPIE-2189"></a>These options are similar to <samp><span class="option">-fpic</span></samp> and <samp><span class="option">-fPIC</span></samp>, but 245generated position independent code can be only linked into executables. 246Usually these options are used when <samp><span class="option">-pie</span></samp> GCC option will be 247used during linking. 248 249 <p><samp><span class="option">-fpie</span></samp> and <samp><span class="option">-fPIE</span></samp> both define the macros 250<code>__pie__</code> and <code>__PIE__</code>. The macros have the value 1 251for <samp><span class="option">-fpie</span></samp> and 2 for <samp><span class="option">-fPIE</span></samp>. 252 253 <br><dt><code>-fno-jump-tables</code><dd><a name="index-fno_002djump_002dtables-2190"></a>Do not use jump tables for switch statements even where it would be 254more efficient than other code generation strategies. This option is 255of use in conjunction with <samp><span class="option">-fpic</span></samp> or <samp><span class="option">-fPIC</span></samp> for 256building code which forms part of a dynamic linker and cannot 257reference the address of a jump table. On some targets, jump tables 258do not require a GOT and this option is not needed. 259 260 <br><dt><code>-ffixed-</code><var>reg</var><dd><a name="index-ffixed-2191"></a>Treat the register named <var>reg</var> as a fixed register; generated code 261should never refer to it (except perhaps as a stack pointer, frame 262pointer or in some other fixed role). 263 264 <p><var>reg</var> must be the name of a register. The register names accepted 265are machine-specific and are defined in the <code>REGISTER_NAMES</code> 266macro in the machine description macro file. 267 268 <p>This flag does not have a negative form, because it specifies a 269three-way choice. 270 271 <br><dt><code>-fcall-used-</code><var>reg</var><dd><a name="index-fcall_002dused-2192"></a>Treat the register named <var>reg</var> as an allocable register that is 272clobbered by function calls. It may be allocated for temporaries or 273variables that do not live across a call. Functions compiled this way 274will not save and restore the register <var>reg</var>. 275 276 <p>It is an error to used this flag with the frame pointer or stack pointer. 277Use of this flag for other registers that have fixed pervasive roles in 278the machine's execution model will produce disastrous results. 279 280 <p>This flag does not have a negative form, because it specifies a 281three-way choice. 282 283 <br><dt><code>-fcall-saved-</code><var>reg</var><dd><a name="index-fcall_002dsaved-2193"></a>Treat the register named <var>reg</var> as an allocable register saved by 284functions. It may be allocated even for temporaries or variables that 285live across a call. Functions compiled this way will save and restore 286the register <var>reg</var> if they use it. 287 288 <p>It is an error to used this flag with the frame pointer or stack pointer. 289Use of this flag for other registers that have fixed pervasive roles in 290the machine's execution model will produce disastrous results. 291 292 <p>A different sort of disaster will result from the use of this flag for 293a register in which function values may be returned. 294 295 <p>This flag does not have a negative form, because it specifies a 296three-way choice. 297 298 <br><dt><code>-fpack-struct[=</code><var>n</var><code>]</code><dd><a name="index-fpack_002dstruct-2194"></a>Without a value specified, pack all structure members together without 299holes. When a value is specified (which must be a small power of two), pack 300structure members according to this value, representing the maximum 301alignment (that is, objects with default alignment requirements larger than 302this will be output potentially unaligned at the next fitting location. 303 304 <p><strong>Warning:</strong> the <samp><span class="option">-fpack-struct</span></samp> switch causes GCC to generate 305code that is not binary compatible with code generated without that switch. 306Additionally, it makes the code suboptimal. 307Use it to conform to a non-default application binary interface. 308 309 <br><dt><code>-finstrument-functions</code><dd><a name="index-finstrument_002dfunctions-2195"></a>Generate instrumentation calls for entry and exit to functions. Just 310after function entry and just before function exit, the following 311profiling functions will be called with the address of the current 312function and its call site. (On some platforms, 313<code>__builtin_return_address</code> does not work beyond the current 314function, so the call site information may not be available to the 315profiling functions otherwise.) 316 317 <pre class="smallexample"> void __cyg_profile_func_enter (void *this_fn, 318 void *call_site); 319 void __cyg_profile_func_exit (void *this_fn, 320 void *call_site); 321</pre> 322 <p>The first argument is the address of the start of the current function, 323which may be looked up exactly in the symbol table. 324 325 <p>This instrumentation is also done for functions expanded inline in other 326functions. The profiling calls will indicate where, conceptually, the 327inline function is entered and exited. This means that addressable 328versions of such functions must be available. If all your uses of a 329function are expanded inline, this may mean an additional expansion of 330code size. If you use ‘<samp><span class="samp">extern inline</span></samp>’ in your C code, an 331addressable version of such functions must be provided. (This is 332normally the case anyways, but if you get lucky and the optimizer always 333expands the functions inline, you might have gotten away without 334providing static copies.) 335 336 <p>A function may be given the attribute <code>no_instrument_function</code>, in 337which case this instrumentation will not be done. This can be used, for 338example, for the profiling functions listed above, high-priority 339interrupt routines, and any functions from which the profiling functions 340cannot safely be called (perhaps signal handlers, if the profiling 341routines generate output or allocate memory). 342 343 <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-2196"></a> 344Set the list of functions that are excluded from instrumentation (see 345the description of <code>-finstrument-functions</code>). If the file that 346contains a function definition matches with one of <var>file</var>, then 347that function is not instrumented. The match is done on substrings: 348if the <var>file</var> parameter is a substring of the file name, it is 349considered to be a match. 350 351 <p>For example: 352 353 <pre class="smallexample"> -finstrument-functions-exclude-file-list=/bits/stl,include/sys 354</pre> 355 <p class="noindent">will exclude any inline function defined in files whose pathnames 356contain <code>/bits/stl</code> or <code>include/sys</code>. 357 358 <p>If, for some reason, you want to include letter <code>','</code> in one of 359<var>sym</var>, write <code>'\,'</code>. For example, 360<code>-finstrument-functions-exclude-file-list='\,\,tmp'</code> 361(note the single quote surrounding the option). 362 363 <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-2197"></a> 364This is similar to <code>-finstrument-functions-exclude-file-list</code>, 365but this option sets the list of function names to be excluded from 366instrumentation. The function name to be matched is its user-visible 367name, such as <code>vector<int> blah(const vector<int> &)</code>, not the 368internal mangled name (e.g., <code>_Z4blahRSt6vectorIiSaIiEE</code>). The 369match is done on substrings: if the <var>sym</var> parameter is a substring 370of the function name, it is considered to be a match. For C99 and C++ 371extended identifiers, the function name must be given in UTF-8, not 372using universal character names. 373 374 <br><dt><code>-finstrument-function-calls</code><dd><a name="index-finstrument_002dfunction_002dcalls-2198"></a>Generate instrumentation calls immediately before and after each 375function call. The following profiling functions will be called with 376the address of the function that is called between them. Use 377<code>__builtin_return_address(0)</code> inside the profiling functions to 378get the addresses from where they are called. 379 380 <pre class="smallexample"> void __cyg_profile_call_enter (void *fn); 381 void __cyg_profile_call_exit (void *fn); 382</pre> 383 <p>Additionally instrumentation calls are inserted at the beginning of 384each function. The argument is the address of the function where the 385insertion occurred. 386 387 <pre class="smallexample"> void __cyg_profile_call_inside (void *fn); 388</pre> 389 <p>If an instrumented function gets inlined, calling 390<code>__builtin_return_address(0)</code> from inside <code>__cyg_profile_call_inside</code> 391will return an address that is in the address range of the function 392where it was inlined into. This can be used to detect if inlining 393occurred for the function that contains <code>__cyg_profile_call_inside</code>. 394 395 <br><dt><code>-fstack-check</code><dd><a name="index-fstack_002dcheck-2199"></a>Generate code to verify that you do not go beyond the boundary of the 396stack. You should specify this flag if you are running in an 397environment with multiple threads, but only rarely need to specify it in 398a single-threaded environment since stack overflow is automatically 399detected on nearly all systems if there is only one stack. 400 401 <p>Note that this switch does not actually cause checking to be done; the 402operating system or the language runtime must do that. The switch causes 403generation of code to ensure that they see the stack being extended. 404 405 <p>You can additionally specify a string parameter: <code>no</code> means no 406checking, <code>generic</code> means force the use of old-style checking, 407<code>specific</code> means use the best checking method and is equivalent 408to bare <samp><span class="option">-fstack-check</span></samp>. 409 410 <p>Old-style checking is a generic mechanism that requires no specific 411target support in the compiler but comes with the following drawbacks: 412 413 <ol type=1 start=1> 414<li>Modified allocation strategy for large objects: they will always be 415allocated dynamically if their size exceeds a fixed threshold. 416 417 <li>Fixed limit on the size of the static frame of functions: when it is 418topped by a particular function, stack checking is not reliable and 419a warning is issued by the compiler. 420 421 <li>Inefficiency: because of both the modified allocation strategy and the 422generic implementation, the performances of the code are hampered. 423 </ol> 424 425 <p>Note that old-style stack checking is also the fallback method for 426<code>specific</code> if no target support has been added in the compiler. 427 428 <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-2200"></a><a name="index-fstack_002dlimit_002dsymbol-2201"></a><a name="index-fno_002dstack_002dlimit-2202"></a>Generate code to ensure that the stack does not grow beyond a certain value, 429either the value of a register or the address of a symbol. If the stack 430would grow beyond the value, a signal is raised. For most targets, 431the signal is raised before the stack overruns the boundary, so 432it is possible to catch the signal without taking special precautions. 433 434 <p>For instance, if the stack starts at absolute address ‘<samp><span class="samp">0x80000000</span></samp>’ 435and grows downwards, you can use the flags 436<samp><span class="option">-fstack-limit-symbol=__stack_limit</span></samp> and 437<samp><span class="option">-Wl,--defsym,__stack_limit=0x7ffe0000</span></samp> to enforce a stack limit 438of 128KB. Note that this may only work with the GNU linker. 439 440 <br><dt><code>-fsplit-stack</code><dd><a name="index-fsplit_002dstack-2203"></a>Generate code to automatically split the stack before it overflows. 441The resulting program has a discontiguous stack which can only 442overflow if the program is unable to allocate any more memory. This 443is most useful when running threaded programs, as it is no longer 444necessary to calculate a good stack size to use for each thread. This 445is currently only implemented for the i386 and x86_64 backends running 446GNU/Linux. 447 448 <p>When code compiled with <samp><span class="option">-fsplit-stack</span></samp> calls code compiled 449without <samp><span class="option">-fsplit-stack</span></samp>, there may not be much stack space 450available for the latter code to run. If compiling all code, 451including library code, with <samp><span class="option">-fsplit-stack</span></samp> is not an option, 452then the linker can fix up these calls so that the code compiled 453without <samp><span class="option">-fsplit-stack</span></samp> always has a large stack. Support for 454this is implemented in the gold linker in GNU binutils release 2.21 455and later. 456 457 <br><dt><code>-fleading-underscore</code><dd><a name="index-fleading_002dunderscore-2204"></a>This option and its counterpart, <samp><span class="option">-fno-leading-underscore</span></samp>, forcibly 458change the way C symbols are represented in the object file. One use 459is to help link with legacy assembly code. 460 461 <p><strong>Warning:</strong> the <samp><span class="option">-fleading-underscore</span></samp> switch causes GCC to 462generate code that is not binary compatible with code generated without that 463switch. Use it to conform to a non-default application binary interface. 464Not all targets provide complete support for this switch. 465 466 <br><dt><code>-ftls-model=</code><var>model</var><dd><a name="index-ftls_002dmodel-2205"></a>Alter the thread-local storage model to be used (see <a href="Thread_002dLocal.html#Thread_002dLocal">Thread-Local</a>). 467The <var>model</var> argument should be one of <code>global-dynamic</code>, 468<code>local-dynamic</code>, <code>initial-exec</code> or <code>local-exec</code>. 469 470 <p>The default without <samp><span class="option">-fpic</span></samp> is <code>initial-exec</code>; with 471<samp><span class="option">-fpic</span></samp> the default is <code>global-dynamic</code>. 472 473 <br><dt><code>-fvisibility=</code><var>default|internal|hidden|protected</var><dd><a name="index-fvisibility-2206"></a>Set the default ELF image symbol visibility to the specified option—all 474symbols will be marked with this unless overridden within the code. 475Using this feature can very substantially improve linking and 476load times of shared object libraries, produce more optimized 477code, provide near-perfect API export and prevent symbol clashes. 478It is <strong>strongly</strong> recommended that you use this in any shared objects 479you distribute. 480 481 <p>Despite the nomenclature, <code>default</code> always means public; i.e., 482available to be linked against from outside the shared object. 483<code>protected</code> and <code>internal</code> are pretty useless in real-world 484usage so the only other commonly used option will be <code>hidden</code>. 485The default if <samp><span class="option">-fvisibility</span></samp> isn't specified is 486<code>default</code>, i.e., make every 487symbol public—this causes the same behavior as previous versions of 488GCC. 489 490 <p>A good explanation of the benefits offered by ensuring ELF 491symbols have the correct visibility is given by “How To Write 492Shared Libraries” by Ulrich Drepper (which can be found at 493<a href="http://people.redhat.com/~drepper/">http://people.redhat.com/~drepper/</a><!-- /@w -->)—however a superior 494solution made possible by this option to marking things hidden when 495the default is public is to make the default hidden and mark things 496public. This is the norm with DLL's on Windows and with <samp><span class="option">-fvisibility=hidden</span></samp> 497and <code>__attribute__ ((visibility("default")))</code> instead of 498<code>__declspec(dllexport)</code> you get almost identical semantics with 499identical syntax. This is a great boon to those working with 500cross-platform projects. 501 502 <p>For those adding visibility support to existing code, you may find 503‘<samp><span class="samp">#pragma GCC visibility</span></samp>’ of use. This works by you enclosing 504the declarations you wish to set visibility for with (for example) 505‘<samp><span class="samp">#pragma GCC visibility push(hidden)</span></samp>’ and 506‘<samp><span class="samp">#pragma GCC visibility pop</span></samp>’. 507Bear in mind that symbol visibility should be viewed <strong>as 508part of the API interface contract</strong> and thus all new code should 509always specify visibility when it is not the default; i.e., declarations 510only for use within the local DSO should <strong>always</strong> be marked explicitly 511as hidden as so to avoid PLT indirection overheads—making this 512abundantly clear also aids readability and self-documentation of the code. 513Note that due to ISO C++ specification requirements, operator new and 514operator delete must always be of default visibility. 515 516 <p>Be aware that headers from outside your project, in particular system 517headers and headers from any other library you use, may not be 518expecting to be compiled with visibility other than the default. You 519may need to explicitly say ‘<samp><span class="samp">#pragma GCC visibility push(default)</span></samp>’ 520before including any such headers. 521 522 <p>‘<samp><span class="samp">extern</span></samp>’ declarations are not affected by ‘<samp><span class="samp">-fvisibility</span></samp>’, so 523a lot of code can be recompiled with ‘<samp><span class="samp">-fvisibility=hidden</span></samp>’ with 524no modifications. However, this means that calls to ‘<samp><span class="samp">extern</span></samp>’ 525functions with no explicit visibility will use the PLT, so it is more 526effective to use ‘<samp><span class="samp">__attribute ((visibility))</span></samp>’ and/or 527‘<samp><span class="samp">#pragma GCC visibility</span></samp>’ to tell the compiler which ‘<samp><span class="samp">extern</span></samp>’ 528declarations should be treated as hidden. 529 530 <p>Note that ‘<samp><span class="samp">-fvisibility</span></samp>’ does affect C++ vague linkage 531entities. This means that, for instance, an exception class that will 532be thrown between DSOs must be explicitly marked with default 533visibility so that the ‘<samp><span class="samp">type_info</span></samp>’ nodes will be unified between 534the DSOs. 535 536 <p>An overview of these techniques, their benefits and how to use them 537is at <a href="http://gcc.gnu.org/wiki/Visibility">http://gcc.gnu.org/wiki/Visibility</a>. 538 539 <br><dt><code>-fstrict-volatile-bitfields</code><dd><a name="index-fstrict_002dvolatile_002dbitfields-2207"></a>This option should be used if accesses to volatile bitfields (or other 540structure fields, although the compiler usually honors those types 541anyway) should use a single access of the width of the 542field's type, aligned to a natural alignment if possible. For 543example, targets with memory-mapped peripheral registers might require 544all such accesses to be 16 bits wide; with this flag the user could 545declare all peripheral bitfields as “unsigned short” (assuming short 546is 16 bits on these targets) to force GCC to use 16 bit accesses 547instead of, perhaps, a more efficient 32 bit access. 548 549 <p>If this option is disabled, the compiler will use the most efficient 550instruction. In the previous example, that might be a 32-bit load 551instruction, even though that will access bytes that do not contain 552any portion of the bitfield, or memory-mapped registers unrelated to 553the one being updated. 554 555 <p>If the target requires strict alignment, and honoring the field 556type would require violating this alignment, a warning is issued. 557If the field has <code>packed</code> attribute, the access is done without 558honoring the field type. If the field doesn't have <code>packed</code> 559attribute, the access is done honoring the field type. In both cases, 560GCC assumes that the user knows something about the target hardware 561that it is unaware of. 562 563 <p>The default value of this option is determined by the application binary 564interface for the target processor. 565 566 </dl> 567 568<!-- man end --> 569 </body></html> 570 571