1<html lang="en"> 2<head> 3<title>Variable Attributes - 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="C-Extensions.html#C-Extensions" title="C Extensions"> 9<link rel="prev" href="Character-Escapes.html#Character-Escapes" title="Character Escapes"> 10<link rel="next" href="Type-Attributes.html#Type-Attributes" title="Type Attributes"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988-2013 Free Software Foundation, Inc. 14 15Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.3 or 17any later version published by the Free Software Foundation; with the 18Invariant Sections being ``Funding Free Software'', the Front-Cover 19Texts being (a) (see below), and with the Back-Cover Texts being (b) 20(see below). A copy of the license is included in the section entitled 21``GNU Free Documentation License''. 22 23(a) The FSF's Front-Cover Text is: 24 25 A GNU Manual 26 27(b) The FSF's Back-Cover Text is: 28 29 You have freedom to copy and modify this GNU Manual, like GNU 30 software. Copies published by the Free Software Foundation raise 31 funds for GNU development.--> 32<meta http-equiv="Content-Style-Type" content="text/css"> 33<style type="text/css"><!-- 34 pre.display { font-family:inherit } 35 pre.format { font-family:inherit } 36 pre.smalldisplay { font-family:inherit; font-size:smaller } 37 pre.smallformat { font-family:inherit; font-size:smaller } 38 pre.smallexample { font-size:smaller } 39 pre.smalllisp { font-size:smaller } 40 span.sc { font-variant:small-caps } 41 span.roman { font-family:serif; font-weight:normal; } 42 span.sansserif { font-family:sans-serif; font-weight:normal; } 43--></style> 44<link rel="stylesheet" type="text/css" href="../cs.css"> 45</head> 46<body> 47<div class="node"> 48<a name="Variable-Attributes"></a> 49<p> 50Next: <a rel="next" accesskey="n" href="Type-Attributes.html#Type-Attributes">Type Attributes</a>, 51Previous: <a rel="previous" accesskey="p" href="Character-Escapes.html#Character-Escapes">Character Escapes</a>, 52Up: <a rel="up" accesskey="u" href="C-Extensions.html#C-Extensions">C Extensions</a> 53<hr> 54</div> 55 56<h3 class="section">6.36 Specifying Attributes of Variables</h3> 57 58<p><a name="index-attribute-of-variables-2774"></a><a name="index-variable-attributes-2775"></a> 59The keyword <code>__attribute__</code> allows you to specify special 60attributes of variables or structure fields. This keyword is followed 61by an attribute specification inside double parentheses. Some 62attributes are currently defined generically for variables. 63Other attributes are defined for variables on particular target 64systems. Other attributes are available for functions 65(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>) and for types (see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>). 66Other front ends might define more attributes 67(see <a href="C_002b_002b-Extensions.html#C_002b_002b-Extensions">Extensions to the C++ Language</a>). 68 69 <p>You may also specify attributes with ‘<samp><span class="samp">__</span></samp>’ preceding and following 70each keyword. This allows you to use them in header files without 71being concerned about a possible macro of the same name. For example, 72you may use <code>__aligned__</code> instead of <code>aligned</code>. 73 74 <p>See <a href="Attribute-Syntax.html#Attribute-Syntax">Attribute Syntax</a>, for details of the exact syntax for using 75attributes. 76 77 78<a name="index-g_t_0040code_007baligned_007d-attribute-2776"></a> 79<dl><dt><code>aligned (</code><var>alignment</var><code>)</code><dd>This attribute specifies a minimum alignment for the variable or 80structure field, measured in bytes. For example, the declaration: 81 82 <pre class="smallexample"> int x __attribute__ ((aligned (16))) = 0; 83</pre> 84 <p class="noindent">causes the compiler to allocate the global variable <code>x</code> on a 8516-byte boundary. On a 68040, this could be used in conjunction with 86an <code>asm</code> expression to access the <code>move16</code> instruction which 87requires 16-byte aligned operands. 88 89 <p>You can also specify the alignment of structure fields. For example, to 90create a double-word aligned <code>int</code> pair, you could write: 91 92 <pre class="smallexample"> struct foo { int x[2] __attribute__ ((aligned (8))); }; 93</pre> 94 <p class="noindent">This is an alternative to creating a union with a <code>double</code> member, 95which forces the union to be double-word aligned. 96 97 <p>As in the preceding examples, you can explicitly specify the alignment 98(in bytes) that you wish the compiler to use for a given variable or 99structure field. Alternatively, you can leave out the alignment factor 100and just ask the compiler to align a variable or field to the 101default alignment for the target architecture you are compiling for. 102The default alignment is sufficient for all scalar types, but may not be 103enough for all vector types on a target that supports vector operations. 104The default alignment is fixed for a particular target ABI. 105 106 <p>GCC also provides a target specific macro <code>__BIGGEST_ALIGNMENT__</code>, 107which is the largest alignment ever used for any data type on the 108target machine you are compiling for. For example, you could write: 109 110 <pre class="smallexample"> short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); 111</pre> 112 <p>The compiler automatically sets the alignment for the declared 113variable or field to <code>__BIGGEST_ALIGNMENT__</code>. Doing this can 114often make copy operations more efficient, because the compiler can 115use whatever instructions copy the biggest chunks of memory when 116performing copies to or from the variables or fields that you have 117aligned this way. Note that the value of <code>__BIGGEST_ALIGNMENT__</code> 118may change depending on command-line options. 119 120 <p>When used on a struct, or struct member, the <code>aligned</code> attribute can 121only increase the alignment; in order to decrease it, the <code>packed</code> 122attribute must be specified as well. When used as part of a typedef, the 123<code>aligned</code> attribute can both increase and decrease alignment, and 124specifying the <code>packed</code> attribute generates a warning. 125 126 <p>Note that the effectiveness of <code>aligned</code> attributes may be limited 127by inherent limitations in your linker. On many systems, the linker is 128only able to arrange for variables to be aligned up to a certain maximum 129alignment. (For some linkers, the maximum supported alignment may 130be very very small.) If your linker is only able to align variables 131up to a maximum of 8-byte alignment, then specifying <code>aligned(16)</code> 132in an <code>__attribute__</code> still only provides you with 8-byte 133alignment. See your linker documentation for further information. 134 135 <p>The <code>aligned</code> attribute can also be used for functions 136(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>.) 137 138 <br><dt><code>cleanup (</code><var>cleanup_function</var><code>)</code><dd><a name="index-g_t_0040code_007bcleanup_007d-attribute-2777"></a>The <code>cleanup</code> attribute runs a function when the variable goes 139out of scope. This attribute can only be applied to auto function 140scope variables; it may not be applied to parameters or variables 141with static storage duration. The function must take one parameter, 142a pointer to a type compatible with the variable. The return value 143of the function (if any) is ignored. 144 145 <p>If <samp><span class="option">-fexceptions</span></samp> is enabled, then <var>cleanup_function</var> 146is run during the stack unwinding that happens during the 147processing of the exception. Note that the <code>cleanup</code> attribute 148does not allow the exception to be caught, only to perform an action. 149It is undefined what happens if <var>cleanup_function</var> does not 150return normally. 151 152 <br><dt><code>common</code><dt><code>nocommon</code><dd><a name="index-g_t_0040code_007bcommon_007d-attribute-2778"></a><a name="index-g_t_0040code_007bnocommon_007d-attribute-2779"></a><a name="index-fcommon-2780"></a><a name="index-fno_002dcommon-2781"></a>The <code>common</code> attribute requests GCC to place a variable in 153“common” storage. The <code>nocommon</code> attribute requests the 154opposite—to allocate space for it directly. 155 156 <p>These attributes override the default chosen by the 157<samp><span class="option">-fno-common</span></samp> and <samp><span class="option">-fcommon</span></samp> flags respectively. 158 159 <br><dt><code>deprecated</code><dt><code>deprecated (</code><var>msg</var><code>)</code><dd><a name="index-g_t_0040code_007bdeprecated_007d-attribute-2782"></a>The <code>deprecated</code> attribute results in a warning if the variable 160is used anywhere in the source file. This is useful when identifying 161variables that are expected to be removed in a future version of a 162program. The warning also includes the location of the declaration 163of the deprecated variable, to enable users to easily find further 164information about why the variable is deprecated, or what they should 165do instead. Note that the warning only occurs for uses: 166 167 <pre class="smallexample"> extern int old_var __attribute__ ((deprecated)); 168 extern int old_var; 169 int new_fn () { return old_var; } 170</pre> 171 <p class="noindent">results in a warning on line 3 but not line 2. The optional <var>msg</var> 172argument, which must be a string, is printed in the warning if 173present. 174 175 <p>The <code>deprecated</code> attribute can also be used for functions and 176types (see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>, see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>.) 177 178 <br><dt><code>mode (</code><var>mode</var><code>)</code><dd><a name="index-g_t_0040code_007bmode_007d-attribute-2783"></a>This attribute specifies the data type for the declaration—whichever 179type corresponds to the mode <var>mode</var>. This in effect lets you 180request an integer or floating-point type according to its width. 181 182 <p>You may also specify a mode of <code>byte</code> or <code>__byte__</code> to 183indicate the mode corresponding to a one-byte integer, <code>word</code> or 184<code>__word__</code> for the mode of a one-word integer, and <code>pointer</code> 185or <code>__pointer__</code> for the mode used to represent pointers. 186 187 <br><dt><code>packed</code><dd><a name="index-g_t_0040code_007bpacked_007d-attribute-2784"></a>The <code>packed</code> attribute specifies that a variable or structure field 188should have the smallest possible alignment—one byte for a variable, 189and one bit for a field, unless you specify a larger value with the 190<code>aligned</code> attribute. 191 192 <p>Here is a structure in which the field <code>x</code> is packed, so that it 193immediately follows <code>a</code>: 194 195 <pre class="smallexample"> struct foo 196 { 197 char a; 198 int x[2] __attribute__ ((packed)); 199 }; 200</pre> 201 <p><em>Note:</em> The 4.1, 4.2 and 4.3 series of GCC ignore the 202<code>packed</code> attribute on bit-fields of type <code>char</code>. This has 203been fixed in GCC 4.4 but the change can lead to differences in the 204structure layout. See the documentation of 205<samp><span class="option">-Wpacked-bitfield-compat</span></samp> for more information. 206 207 <br><dt><code>section ("</code><var>section-name</var><code>")</code><dd><a name="index-g_t_0040code_007bsection_007d-variable-attribute-2785"></a>Normally, the compiler places the objects it generates in sections like 208<code>data</code> and <code>bss</code>. Sometimes, however, you need additional sections, 209or you need certain particular variables to appear in special sections, 210for example to map to special hardware. The <code>section</code> 211attribute specifies that a variable (or function) lives in a particular 212section. For example, this small program uses several specific section names: 213 214 <pre class="smallexample"> struct duart a __attribute__ ((section ("DUART_A"))) = { 0 }; 215 struct duart b __attribute__ ((section ("DUART_B"))) = { 0 }; 216 char stack[10000] __attribute__ ((section ("STACK"))) = { 0 }; 217 int init_data __attribute__ ((section ("INITDATA"))); 218 219 main() 220 { 221 /* <span class="roman">Initialize stack pointer</span> */ 222 init_sp (stack + sizeof (stack)); 223 224 /* <span class="roman">Initialize initialized data</span> */ 225 memcpy (&init_data, &data, &edata - &data); 226 227 /* <span class="roman">Turn on the serial ports</span> */ 228 init_duart (&a); 229 init_duart (&b); 230 } 231</pre> 232 <p class="noindent">Use the <code>section</code> attribute with 233<em>global</em> variables and not <em>local</em> variables, 234as shown in the example. 235 236 <p>You may use the <code>section</code> attribute with initialized or 237uninitialized global variables but the linker requires 238each object be defined once, with the exception that uninitialized 239variables tentatively go in the <code>common</code> (or <code>bss</code>) section 240and can be multiply “defined”. Using the <code>section</code> attribute 241changes what section the variable goes into and may cause the 242linker to issue an error if an uninitialized variable has multiple 243definitions. You can force a variable to be initialized with the 244<samp><span class="option">-fno-common</span></samp> flag or the <code>nocommon</code> attribute. 245 246 <p>Some file formats do not support arbitrary sections so the <code>section</code> 247attribute is not available on all platforms. 248If you need to map the entire contents of a module to a particular 249section, consider using the facilities of the linker instead. 250 251 <br><dt><code>shared</code><dd><a name="index-g_t_0040code_007bshared_007d-variable-attribute-2786"></a>On Microsoft Windows, in addition to putting variable definitions in a named 252section, the section can also be shared among all running copies of an 253executable or DLL. For example, this small program defines shared data 254by putting it in a named section <code>shared</code> and marking the section 255shareable: 256 257 <pre class="smallexample"> int foo __attribute__((section ("shared"), shared)) = 0; 258 259 int 260 main() 261 { 262 /* <span class="roman">Read and write foo. All running 263 copies see the same value.</span> */ 264 return 0; 265 } 266</pre> 267 <p class="noindent">You may only use the <code>shared</code> attribute along with <code>section</code> 268attribute with a fully-initialized global definition because of the way 269linkers work. See <code>section</code> attribute for more information. 270 271 <p>The <code>shared</code> attribute is only available on Microsoft Windows. 272 273 <br><dt><code>tls_model ("</code><var>tls_model</var><code>")</code><dd><a name="index-g_t_0040code_007btls_005fmodel_007d-attribute-2787"></a>The <code>tls_model</code> attribute sets thread-local storage model 274(see <a href="Thread_002dLocal.html#Thread_002dLocal">Thread-Local</a>) of a particular <code>__thread</code> variable, 275overriding <samp><span class="option">-ftls-model=</span></samp> command-line switch on a per-variable 276basis. 277The <var>tls_model</var> argument should be one of <code>global-dynamic</code>, 278<code>local-dynamic</code>, <code>initial-exec</code> or <code>local-exec</code>. 279 280 <p>Not all targets support this attribute. 281 282 <br><dt><code>unused</code><dd>This attribute, attached to a variable, means that the variable is meant 283to be possibly unused. GCC does not produce a warning for this 284variable. 285 286 <br><dt><code>used</code><dd>This attribute, attached to a variable, means that the variable must be 287emitted even if it appears that the variable is not referenced. 288 289 <p>When applied to a static data member of a C++ class template, the 290attribute also means that the member is instantiated if the 291class itself is instantiated. 292 293 <br><dt><code>vector_size (</code><var>bytes</var><code>)</code><dd>This attribute specifies the vector size for the variable, measured in 294bytes. For example, the declaration: 295 296 <pre class="smallexample"> int foo __attribute__ ((vector_size (16))); 297</pre> 298 <p class="noindent">causes the compiler to set the mode for <code>foo</code>, to be 16 bytes, 299divided into <code>int</code> sized units. Assuming a 32-bit int (a vector of 3004 units of 4 bytes), the corresponding mode of <code>foo</code> is V4SI. 301 302 <p>This attribute is only applicable to integral and float scalars, 303although arrays, pointers, and function return values are allowed in 304conjunction with this construct. 305 306 <p>Aggregates with this attribute are invalid, even if they are of the same 307size as a corresponding scalar. For example, the declaration: 308 309 <pre class="smallexample"> struct S { int a; }; 310 struct S __attribute__ ((vector_size (16))) foo; 311</pre> 312 <p class="noindent">is invalid even if the size of the structure is the same as the size of 313the <code>int</code>. 314 315 <br><dt><code>selectany</code><dd>The <code>selectany</code> attribute causes an initialized global variable to 316have link-once semantics. When multiple definitions of the variable are 317encountered by the linker, the first is selected and the remainder are 318discarded. Following usage by the Microsoft compiler, the linker is told 319<em>not</em> to warn about size or content differences of the multiple 320definitions. 321 322 <p>Although the primary usage of this attribute is for POD types, the 323attribute can also be applied to global C++ objects that are initialized 324by a constructor. In this case, the static initialization and destruction 325code for the object is emitted in each translation defining the object, 326but the calls to the constructor and destructor are protected by a 327link-once guard variable. 328 329 <p>The <code>selectany</code> attribute is only available on Microsoft Windows 330targets. You can use <code>__declspec (selectany)</code> as a synonym for 331<code>__attribute__ ((selectany))</code> for compatibility with other 332compilers. 333 334 <br><dt><code>weak</code><dd>The <code>weak</code> attribute is described in <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>. 335 336 <br><dt><code>dllimport</code><dd>The <code>dllimport</code> attribute is described in <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>. 337 338 <br><dt><code>dllexport</code><dd>The <code>dllexport</code> attribute is described in <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>. 339 340 </dl> 341 342 <p><a name="AVR-Variable-Attributes"></a> 343 344<h4 class="subsection">6.36.1 AVR Variable Attributes</h4> 345 346 <dl> 347<dt><code>progmem</code><dd><a name="index-g_t_0040code_007bprogmem_007d-AVR-variable-attribute-2788"></a>The <code>progmem</code> attribute is used on the AVR to place read-only 348data in the non-volatile program memory (flash). The <code>progmem</code> 349attribute accomplishes this by putting respective variables into a 350section whose name starts with <code>.progmem</code>. 351 352 <p>This attribute works similar to the <code>section</code> attribute 353but adds additional checking. Notice that just like the 354<code>section</code> attribute, <code>progmem</code> affects the location 355of the data but not how this data is accessed. 356 357 <p>In order to read data located with the <code>progmem</code> attribute 358(inline) assembler must be used. 359 <pre class="smallexample"> /* Use custom macros from <a href="http://nongnu.org/avr-libc/user-manual/">AVR-LibC</a><!-- /@w --> */ 360 #include <avr/pgmspace.h> 361 362 /* Locate var in flash memory */ 363 const int var[2] PROGMEM = { 1, 2 }; 364 365 int read_var (int i) 366 { 367 /* Access var[] by accessor macro from avr/pgmspace.h */ 368 return (int) pgm_read_word (& var[i]); 369 } 370</pre> 371 <p>AVR is a Harvard architecture processor and data and read-only data 372normally resides in the data memory (RAM). 373 374 <p>See also the <a href="AVR-Named-Address-Spaces.html#AVR-Named-Address-Spaces">AVR Named Address Spaces</a> section for 375an alternate way to locate and access data in flash memory. 376</dl> 377 378<h4 class="subsection">6.36.2 Blackfin Variable Attributes</h4> 379 380<p>Three attributes are currently defined for the Blackfin. 381 382 <dl> 383<dt><code>l1_data</code><dt><code>l1_data_A</code><dt><code>l1_data_B</code><dd><a name="index-g_t_0040code_007bl1_005fdata_007d-variable-attribute-2789"></a><a name="index-g_t_0040code_007bl1_005fdata_005fA_007d-variable-attribute-2790"></a><a name="index-g_t_0040code_007bl1_005fdata_005fB_007d-variable-attribute-2791"></a>Use these attributes on the Blackfin to place the variable into L1 Data SRAM. 384Variables with <code>l1_data</code> attribute are put into the specific section 385named <code>.l1.data</code>. Those with <code>l1_data_A</code> attribute are put into 386the specific section named <code>.l1.data.A</code>. Those with <code>l1_data_B</code> 387attribute are put into the specific section named <code>.l1.data.B</code>. 388 389 <br><dt><code>l2</code><dd><a name="index-g_t_0040code_007bl2_007d-variable-attribute-2792"></a>Use this attribute on the Blackfin to place the variable into L2 SRAM. 390Variables with <code>l2</code> attribute are put into the specific section 391named <code>.l2.data</code>. 392</dl> 393 394<h4 class="subsection">6.36.3 M32R/D Variable Attributes</h4> 395 396<p>One attribute is currently defined for the M32R/D. 397 398 <dl> 399<dt><code>model (</code><var>model-name</var><code>)</code><dd><a name="index-variable-addressability-on-the-M32R_002fD-2793"></a>Use this attribute on the M32R/D to set the addressability of an object. 400The identifier <var>model-name</var> is one of <code>small</code>, <code>medium</code>, 401or <code>large</code>, representing each of the code models. 402 403 <p>Small model objects live in the lower 16MB of memory (so that their 404addresses can be loaded with the <code>ld24</code> instruction). 405 406 <p>Medium and large model objects may live anywhere in the 32-bit address space 407(the compiler generates <code>seth/add3</code> instructions to load their 408addresses). 409</dl> 410 411 <p><a name="MeP-Variable-Attributes"></a> 412 413<h4 class="subsection">6.36.4 MeP Variable Attributes</h4> 414 415<p>The MeP target has a number of addressing modes and busses. The 416<code>near</code> space spans the standard memory space's first 16 megabytes 417(24 bits). The <code>far</code> space spans the entire 32-bit memory space. 418The <code>based</code> space is a 128-byte region in the memory space that 419is addressed relative to the <code>$tp</code> register. The <code>tiny</code> 420space is a 65536-byte region relative to the <code>$gp</code> register. In 421addition to these memory regions, the MeP target has a separate 16-bit 422control bus which is specified with <code>cb</code> attributes. 423 424 <dl> 425<dt><code>based</code><dd>Any variable with the <code>based</code> attribute is assigned to the 426<code>.based</code> section, and is accessed with relative to the 427<code>$tp</code> register. 428 429 <br><dt><code>tiny</code><dd>Likewise, the <code>tiny</code> attribute assigned variables to the 430<code>.tiny</code> section, relative to the <code>$gp</code> register. 431 432 <br><dt><code>near</code><dd>Variables with the <code>near</code> attribute are assumed to have addresses 433that fit in a 24-bit addressing mode. This is the default for large 434variables (<code>-mtiny=4</code> is the default) but this attribute can 435override <code>-mtiny=</code> for small variables, or override <code>-ml</code>. 436 437 <br><dt><code>far</code><dd>Variables with the <code>far</code> attribute are addressed using a full 43832-bit address. Since this covers the entire memory space, this 439allows modules to make no assumptions about where variables might be 440stored. 441 442 <br><dt><code>io</code><dt><code>io (</code><var>addr</var><code>)</code><dd>Variables with the <code>io</code> attribute are used to address 443memory-mapped peripherals. If an address is specified, the variable 444is assigned that address, else it is not assigned an address (it is 445assumed some other module assigns an address). Example: 446 447 <pre class="smallexample"> int timer_count __attribute__((io(0x123))); 448</pre> 449 <br><dt><code>cb</code><dt><code>cb (</code><var>addr</var><code>)</code><dd>Variables with the <code>cb</code> attribute are used to access the control 450bus, using special instructions. <code>addr</code> indicates the control bus 451address. Example: 452 453 <pre class="smallexample"> int cpu_clock __attribute__((cb(0x123))); 454</pre> 455 </dl> 456 457 <p><a name="i386-Variable-Attributes"></a> 458 459<h4 class="subsection">6.36.5 i386 Variable Attributes</h4> 460 461<p>Two attributes are currently defined for i386 configurations: 462<code>ms_struct</code> and <code>gcc_struct</code> 463 464 <dl> 465<dt><code>ms_struct</code><dt><code>gcc_struct</code><dd><a name="index-g_t_0040code_007bms_005fstruct_007d-attribute-2794"></a><a name="index-g_t_0040code_007bgcc_005fstruct_007d-attribute-2795"></a> 466If <code>packed</code> is used on a structure, or if bit-fields are used, 467it may be that the Microsoft ABI lays out the structure differently 468than the way GCC normally does. Particularly when moving packed 469data between functions compiled with GCC and the native Microsoft compiler 470(either via function call or as data in a file), it may be necessary to access 471either format. 472 473 <p>Currently <samp><span class="option">-m[no-]ms-bitfields</span></samp> is provided for the Microsoft Windows X86 474compilers to match the native Microsoft compiler. 475 476 <p>The Microsoft structure layout algorithm is fairly simple with the exception 477of the bit-field packing. 478The padding and alignment of members of structures and whether a bit-field 479can straddle a storage-unit boundary are determine by these rules: 480 481 <ol type=1 start=1> 482<li>Structure members are stored sequentially in the order in which they are 483declared: the first member has the lowest memory address and the last member 484the highest. 485 486 <li>Every data object has an alignment requirement. The alignment requirement 487for all data except structures, unions, and arrays is either the size of the 488object or the current packing size (specified with either the 489<code>aligned</code> attribute or the <code>pack</code> pragma), 490whichever is less. For structures, unions, and arrays, 491the alignment requirement is the largest alignment requirement of its members. 492Every object is allocated an offset so that: 493 494 <pre class="smallexample"> offset % alignment_requirement == 0 495</pre> 496 <li>Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation 497unit if the integral types are the same size and if the next bit-field fits 498into the current allocation unit without crossing the boundary imposed by the 499common alignment requirements of the bit-fields. 500 </ol> 501 502 <p>MSVC interprets zero-length bit-fields in the following ways: 503 504 <ol type=1 start=1> 505<li>If a zero-length bit-field is inserted between two bit-fields that 506are normally coalesced, the bit-fields are not coalesced. 507 508 <p>For example: 509 510 <pre class="smallexample"> struct 511 { 512 unsigned long bf_1 : 12; 513 unsigned long : 0; 514 unsigned long bf_2 : 12; 515 } t1; 516</pre> 517 <p class="noindent">The size of <code>t1</code> is 8 bytes with the zero-length bit-field. If the 518zero-length bit-field were removed, <code>t1</code>'s size would be 4 bytes. 519 520 <li>If a zero-length bit-field is inserted after a bit-field, <code>foo</code>, and the 521alignment of the zero-length bit-field is greater than the member that follows it, 522<code>bar</code>, <code>bar</code> is aligned as the type of the zero-length bit-field. 523 524 <p>For example: 525 526 <pre class="smallexample"> struct 527 { 528 char foo : 4; 529 short : 0; 530 char bar; 531 } t2; 532 533 struct 534 { 535 char foo : 4; 536 short : 0; 537 double bar; 538 } t3; 539</pre> 540 <p class="noindent">For <code>t2</code>, <code>bar</code> is placed at offset 2, rather than offset 1. 541Accordingly, the size of <code>t2</code> is 4. For <code>t3</code>, the zero-length 542bit-field does not affect the alignment of <code>bar</code> or, as a result, the size 543of the structure. 544 545 <p>Taking this into account, it is important to note the following: 546 547 <ol type=1 start=1> 548<li>If a zero-length bit-field follows a normal bit-field, the type of the 549zero-length bit-field may affect the alignment of the structure as whole. For 550example, <code>t2</code> has a size of 4 bytes, since the zero-length bit-field follows a 551normal bit-field, and is of type short. 552 553 <li>Even if a zero-length bit-field is not followed by a normal bit-field, it may 554still affect the alignment of the structure: 555 556 <pre class="smallexample"> struct 557 { 558 char foo : 6; 559 long : 0; 560 } t4; 561</pre> 562 <p class="noindent">Here, <code>t4</code> takes up 4 bytes. 563 </ol> 564 565 <li>Zero-length bit-fields following non-bit-field members are ignored: 566 567 <pre class="smallexample"> struct 568 { 569 char foo; 570 long : 0; 571 char bar; 572 } t5; 573</pre> 574 <p class="noindent">Here, <code>t5</code> takes up 2 bytes. 575 </ol> 576</dl> 577 578<h4 class="subsection">6.36.6 PowerPC Variable Attributes</h4> 579 580<p>Three attributes currently are defined for PowerPC configurations: 581<code>altivec</code>, <code>ms_struct</code> and <code>gcc_struct</code>. 582 583 <p>For full documentation of the struct attributes please see the 584documentation in <a href="i386-Variable-Attributes.html#i386-Variable-Attributes">i386 Variable Attributes</a>. 585 586 <p>For documentation of <code>altivec</code> attribute please see the 587documentation in <a href="PowerPC-Type-Attributes.html#PowerPC-Type-Attributes">PowerPC Type Attributes</a>. 588 589<h4 class="subsection">6.36.7 SPU Variable Attributes</h4> 590 591<p>The SPU supports the <code>spu_vector</code> attribute for variables. For 592documentation of this attribute please see the documentation in 593<a href="SPU-Type-Attributes.html#SPU-Type-Attributes">SPU Type Attributes</a>. 594 595<h4 class="subsection">6.36.8 Xstormy16 Variable Attributes</h4> 596 597<p>One attribute is currently defined for xstormy16 configurations: 598<code>below100</code>. 599 600 <dl> 601<dt><code>below100</code><dd><a name="index-g_t_0040code_007bbelow100_007d-attribute-2796"></a> 602If a variable has the <code>below100</code> attribute (<code>BELOW100</code> is 603allowed also), GCC places the variable in the first 0x100 bytes of 604memory and use special opcodes to access it. Such variables are 605placed in either the <code>.bss_below100</code> section or the 606<code>.data_below100</code> section. 607 608 </dl> 609 610 </body></html> 611 612