1<html lang="en"> 2<head> 3<title>Type 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="Variable-Attributes.html#Variable-Attributes" title="Variable Attributes"> 10<link rel="next" href="Alignment.html#Alignment" title="Alignment"> 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="Type-Attributes"></a> 49<p> 50Next: <a rel="next" accesskey="n" href="Alignment.html#Alignment">Alignment</a>, 51Previous: <a rel="previous" accesskey="p" href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</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.37 Specifying Attributes of Types</h3> 57 58<p><a name="index-attribute-of-types-2797"></a><a name="index-type-attributes-2798"></a> 59The keyword <code>__attribute__</code> allows you to specify special 60attributes of <code>struct</code> and <code>union</code> types when you define 61such types. This keyword is followed by an attribute specification 62inside double parentheses. Seven attributes are currently defined for 63types: <code>aligned</code>, <code>packed</code>, <code>transparent_union</code>, 64<code>unused</code>, <code>deprecated</code>, <code>visibility</code>, and 65<code>may_alias</code>. Other attributes are defined for functions 66(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>) and for variables (see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>). 67 68 <p>You may also specify any one of these attributes with ‘<samp><span class="samp">__</span></samp>’ 69preceding and following its keyword. This allows you to use these 70attributes in header files without being concerned about a possible 71macro of the same name. For example, you may use <code>__aligned__</code> 72instead of <code>aligned</code>. 73 74 <p>You may specify type attributes in an enum, struct or union type 75declaration or definition, or for other types in a <code>typedef</code> 76declaration. 77 78 <p>For an enum, struct or union type, you may specify attributes either 79between the enum, struct or union tag and the name of the type, or 80just past the closing curly brace of the <em>definition</em>. The 81former syntax is preferred. 82 83 <p>See <a href="Attribute-Syntax.html#Attribute-Syntax">Attribute Syntax</a>, for details of the exact syntax for using 84attributes. 85 86 87<a name="index-g_t_0040code_007baligned_007d-attribute-2799"></a> 88<dl><dt><code>aligned (</code><var>alignment</var><code>)</code><dd>This attribute specifies a minimum alignment (in bytes) for variables 89of the specified type. For example, the declarations: 90 91 <pre class="smallexample"> struct S { short f[3]; } __attribute__ ((aligned (8))); 92 typedef int more_aligned_int __attribute__ ((aligned (8))); 93</pre> 94 <p class="noindent">force the compiler to ensure (as far as it can) that each variable whose 95type is <code>struct S</code> or <code>more_aligned_int</code> is allocated and 96aligned <em>at least</em> on a 8-byte boundary. On a SPARC, having all 97variables of type <code>struct S</code> aligned to 8-byte boundaries allows 98the compiler to use the <code>ldd</code> and <code>std</code> (doubleword load and 99store) instructions when copying one variable of type <code>struct S</code> to 100another, thus improving run-time efficiency. 101 102 <p>Note that the alignment of any given <code>struct</code> or <code>union</code> type 103is required by the ISO C standard to be at least a perfect multiple of 104the lowest common multiple of the alignments of all of the members of 105the <code>struct</code> or <code>union</code> in question. This means that you <em>can</em> 106effectively adjust the alignment of a <code>struct</code> or <code>union</code> 107type by attaching an <code>aligned</code> attribute to any one of the members 108of such a type, but the notation illustrated in the example above is a 109more obvious, intuitive, and readable way to request the compiler to 110adjust the alignment of an entire <code>struct</code> or <code>union</code> type. 111 112 <p>As in the preceding example, you can explicitly specify the alignment 113(in bytes) that you wish the compiler to use for a given <code>struct</code> 114or <code>union</code> type. Alternatively, you can leave out the alignment factor 115and just ask the compiler to align a type to the maximum 116useful alignment for the target machine you are compiling for. For 117example, you could write: 118 119 <pre class="smallexample"> struct S { short f[3]; } __attribute__ ((aligned)); 120</pre> 121 <p>Whenever you leave out the alignment factor in an <code>aligned</code> 122attribute specification, the compiler automatically sets the alignment 123for the type to the largest alignment that is ever used for any data 124type on the target machine you are compiling for. Doing this can often 125make copy operations more efficient, because the compiler can use 126whatever instructions copy the biggest chunks of memory when performing 127copies to or from the variables that have types that you have aligned 128this way. 129 130 <p>In the example above, if the size of each <code>short</code> is 2 bytes, then 131the size of the entire <code>struct S</code> type is 6 bytes. The smallest 132power of two that is greater than or equal to that is 8, so the 133compiler sets the alignment for the entire <code>struct S</code> type to 8 134bytes. 135 136 <p>Note that although you can ask the compiler to select a time-efficient 137alignment for a given type and then declare only individual stand-alone 138objects of that type, the compiler's ability to select a time-efficient 139alignment is primarily useful only when you plan to create arrays of 140variables having the relevant (efficiently aligned) type. If you 141declare or use arrays of variables of an efficiently-aligned type, then 142it is likely that your program also does pointer arithmetic (or 143subscripting, which amounts to the same thing) on pointers to the 144relevant type, and the code that the compiler generates for these 145pointer arithmetic operations is often more efficient for 146efficiently-aligned types than for other types. 147 148 <p>The <code>aligned</code> attribute can only increase the alignment; but you 149can decrease it by specifying <code>packed</code> as well. See below. 150 151 <p>Note that the effectiveness of <code>aligned</code> attributes may be limited 152by inherent limitations in your linker. On many systems, the linker is 153only able to arrange for variables to be aligned up to a certain maximum 154alignment. (For some linkers, the maximum supported alignment may 155be very very small.) If your linker is only able to align variables 156up to a maximum of 8-byte alignment, then specifying <code>aligned(16)</code> 157in an <code>__attribute__</code> still only provides you with 8-byte 158alignment. See your linker documentation for further information. 159 160 <br><dt><code>packed</code><dd>This attribute, attached to <code>struct</code> or <code>union</code> type 161definition, specifies that each member (other than zero-width bit-fields) 162of the structure or union is placed to minimize the memory required. When 163attached to an <code>enum</code> definition, it indicates that the smallest 164integral type should be used. 165 166 <p><a name="index-fshort_002denums-2800"></a>Specifying this attribute for <code>struct</code> and <code>union</code> types is 167equivalent to specifying the <code>packed</code> attribute on each of the 168structure or union members. Specifying the <samp><span class="option">-fshort-enums</span></samp> 169flag on the line is equivalent to specifying the <code>packed</code> 170attribute on all <code>enum</code> definitions. 171 172 <p>In the following example <code>struct my_packed_struct</code>'s members are 173packed closely together, but the internal layout of its <code>s</code> member 174is not packed—to do that, <code>struct my_unpacked_struct</code> needs to 175be packed too. 176 177 <pre class="smallexample"> struct my_unpacked_struct 178 { 179 char c; 180 int i; 181 }; 182 183 struct __attribute__ ((__packed__)) my_packed_struct 184 { 185 char c; 186 int i; 187 struct my_unpacked_struct s; 188 }; 189</pre> 190 <p>You may only specify this attribute on the definition of an <code>enum</code>, 191<code>struct</code> or <code>union</code>, not on a <code>typedef</code> that does not 192also define the enumerated type, structure or union. 193 194 <br><dt><code>transparent_union</code><dd>This attribute, attached to a <code>union</code> type definition, indicates 195that any function parameter having that union type causes calls to that 196function to be treated in a special way. 197 198 <p>First, the argument corresponding to a transparent union type can be of 199any type in the union; no cast is required. Also, if the union contains 200a pointer type, the corresponding argument can be a null pointer 201constant or a void pointer expression; and if the union contains a void 202pointer type, the corresponding argument can be any pointer expression. 203If the union member type is a pointer, qualifiers like <code>const</code> on 204the referenced type must be respected, just as with normal pointer 205conversions. 206 207 <p>Second, the argument is passed to the function using the calling 208conventions of the first member of the transparent union, not the calling 209conventions of the union itself. All members of the union must have the 210same machine representation; this is necessary for this argument passing 211to work properly. 212 213 <p>Transparent unions are designed for library functions that have multiple 214interfaces for compatibility reasons. For example, suppose the 215<code>wait</code> function must accept either a value of type <code>int *</code> to 216comply with POSIX, or a value of type <code>union wait *</code> to comply with 217the 4.1BSD interface. If <code>wait</code>'s parameter were <code>void *</code>, 218<code>wait</code> would accept both kinds of arguments, but it would also 219accept any other pointer type and this would make argument type checking 220less useful. Instead, <code><sys/wait.h></code> might define the interface 221as follows: 222 223 <pre class="smallexample"> typedef union __attribute__ ((__transparent_union__)) 224 { 225 int *__ip; 226 union wait *__up; 227 } wait_status_ptr_t; 228 229 pid_t wait (wait_status_ptr_t); 230</pre> 231 <p class="noindent">This interface allows either <code>int *</code> or <code>union wait *</code> 232arguments to be passed, using the <code>int *</code> calling convention. 233The program can call <code>wait</code> with arguments of either type: 234 235 <pre class="smallexample"> int w1 () { int w; return wait (&w); } 236 int w2 () { union wait w; return wait (&w); } 237</pre> 238 <p class="noindent">With this interface, <code>wait</code>'s implementation might look like this: 239 240 <pre class="smallexample"> pid_t wait (wait_status_ptr_t p) 241 { 242 return waitpid (-1, p.__ip, 0); 243 } 244</pre> 245 <br><dt><code>unused</code><dd>When attached to a type (including a <code>union</code> or a <code>struct</code>), 246this attribute means that variables of that type are meant to appear 247possibly unused. GCC does not produce a warning for any variables of 248that type, even if the variable appears to do nothing. This is often 249the case with lock or thread classes, which are usually defined and then 250not referenced, but contain constructors and destructors that have 251nontrivial bookkeeping functions. 252 253 <br><dt><code>deprecated</code><dt><code>deprecated (</code><var>msg</var><code>)</code><dd>The <code>deprecated</code> attribute results in a warning if the type 254is used anywhere in the source file. This is useful when identifying 255types that are expected to be removed in a future version of a program. 256If possible, the warning also includes the location of the declaration 257of the deprecated type, to enable users to easily find further 258information about why the type is deprecated, or what they should do 259instead. Note that the warnings only occur for uses and then only 260if the type is being applied to an identifier that itself is not being 261declared as deprecated. 262 263 <pre class="smallexample"> typedef int T1 __attribute__ ((deprecated)); 264 T1 x; 265 typedef T1 T2; 266 T2 y; 267 typedef T1 T3 __attribute__ ((deprecated)); 268 T3 z __attribute__ ((deprecated)); 269</pre> 270 <p class="noindent">results in a warning on line 2 and 3 but not lines 4, 5, or 6. No 271warning is issued for line 4 because T2 is not explicitly 272deprecated. Line 5 has no warning because T3 is explicitly 273deprecated. Similarly for line 6. The optional <var>msg</var> 274argument, which must be a string, is printed in the warning if 275present. 276 277 <p>The <code>deprecated</code> attribute can also be used for functions and 278variables (see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>, see <a href="Variable-Attributes.html#Variable-Attributes">Variable Attributes</a>.) 279 280 <br><dt><code>may_alias</code><dd>Accesses through pointers to types with this attribute are not subject 281to type-based alias analysis, but are instead assumed to be able to alias 282any other type of objects. 283In the context of section 6.5 paragraph 7 of the C99 standard, 284an lvalue expression 285dereferencing such a pointer is treated like having a character type. 286See <samp><span class="option">-fstrict-aliasing</span></samp> for more information on aliasing issues. 287This extension exists to support some vector APIs, in which pointers to 288one vector type are permitted to alias pointers to a different vector type. 289 290 <p>Note that an object of a type with this attribute does not have any 291special semantics. 292 293 <p>Example of use: 294 295 <pre class="smallexample"> typedef short __attribute__((__may_alias__)) short_a; 296 297 int 298 main (void) 299 { 300 int a = 0x12345678; 301 short_a *b = (short_a *) &a; 302 303 b[1] = 0; 304 305 if (a == 0x12345678) 306 abort(); 307 308 exit(0); 309 } 310</pre> 311 <p class="noindent">If you replaced <code>short_a</code> with <code>short</code> in the variable 312declaration, the above program would abort when compiled with 313<samp><span class="option">-fstrict-aliasing</span></samp>, which is on by default at <samp><span class="option">-O2</span></samp> or 314above in recent GCC versions. 315 316 <br><dt><code>visibility</code><dd>In C++, attribute visibility (see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>) can also be 317applied to class, struct, union and enum types. Unlike other type 318attributes, the attribute must appear between the initial keyword and 319the name of the type; it cannot appear after the body of the type. 320 321 <p>Note that the type visibility is applied to vague linkage entities 322associated with the class (vtable, typeinfo node, etc.). In 323particular, if a class is thrown as an exception in one shared object 324and caught in another, the class must have default visibility. 325Otherwise the two shared objects are unable to use the same 326typeinfo node and exception handling will break. 327 328 </dl> 329 330 <p>To specify multiple attributes, separate them by commas within the 331double parentheses: for example, ‘<samp><span class="samp">__attribute__ ((aligned (16), 332packed))</span></samp>’. 333 334<h4 class="subsection">6.37.1 ARM Type Attributes</h4> 335 336<p>On those ARM targets that support <code>dllimport</code> (such as Symbian 337OS), you can use the <code>notshared</code> attribute to indicate that the 338virtual table and other similar data for a class should not be 339exported from a DLL. For example: 340 341<pre class="smallexample"> class __declspec(notshared) C { 342 public: 343 __declspec(dllimport) C(); 344 virtual void f(); 345 } 346 347 __declspec(dllexport) 348 C::C() {} 349</pre> 350 <p class="noindent">In this code, <code>C::C</code> is exported from the current DLL, but the 351virtual table for <code>C</code> is not exported. (You can use 352<code>__attribute__</code> instead of <code>__declspec</code> if you prefer, but 353most Symbian OS code uses <code>__declspec</code>.) 354 355 <p><a name="MeP-Type-Attributes"></a> 356 357<h4 class="subsection">6.37.2 MeP Type Attributes</h4> 358 359<p>Many of the MeP variable attributes may be applied to types as well. 360Specifically, the <code>based</code>, <code>tiny</code>, <code>near</code>, and 361<code>far</code> attributes may be applied to either. The <code>io</code> and 362<code>cb</code> attributes may not be applied to types. 363 364 <p><a name="i386-Type-Attributes"></a> 365 366<h4 class="subsection">6.37.3 i386 Type Attributes</h4> 367 368<p>Two attributes are currently defined for i386 configurations: 369<code>ms_struct</code> and <code>gcc_struct</code>. 370 371 <dl> 372<dt><code>ms_struct</code><dt><code>gcc_struct</code><dd><a name="index-g_t_0040code_007bms_005fstruct_007d-2801"></a><a name="index-g_t_0040code_007bgcc_005fstruct_007d-2802"></a> 373If <code>packed</code> is used on a structure, or if bit-fields are used 374it may be that the Microsoft ABI packs them differently 375than GCC normally packs them. Particularly when moving packed 376data between functions compiled with GCC and the native Microsoft compiler 377(either via function call or as data in a file), it may be necessary to access 378either format. 379 380 <p>Currently <samp><span class="option">-m[no-]ms-bitfields</span></samp> is provided for the Microsoft Windows X86 381compilers to match the native Microsoft compiler. 382</dl> 383 384 <p><a name="PowerPC-Type-Attributes"></a> 385 386<h4 class="subsection">6.37.4 PowerPC Type Attributes</h4> 387 388<p>Three attributes currently are defined for PowerPC configurations: 389<code>altivec</code>, <code>ms_struct</code> and <code>gcc_struct</code>. 390 391 <p>For full documentation of the <code>ms_struct</code> and <code>gcc_struct</code> 392attributes please see the documentation in <a href="i386-Type-Attributes.html#i386-Type-Attributes">i386 Type Attributes</a>. 393 394 <p>The <code>altivec</code> attribute allows one to declare AltiVec vector data 395types supported by the AltiVec Programming Interface Manual. The 396attribute requires an argument to specify one of three vector types: 397<code>vector__</code>, <code>pixel__</code> (always followed by unsigned short), 398and <code>bool__</code> (always followed by unsigned). 399 400<pre class="smallexample"> __attribute__((altivec(vector__))) 401 __attribute__((altivec(pixel__))) unsigned short 402 __attribute__((altivec(bool__))) unsigned 403</pre> 404 <p>These attributes mainly are intended to support the <code>__vector</code>, 405<code>__pixel</code>, and <code>__bool</code> AltiVec keywords. 406 407 <p><a name="SPU-Type-Attributes"></a> 408 409<h4 class="subsection">6.37.5 SPU Type Attributes</h4> 410 411<p>The SPU supports the <code>spu_vector</code> attribute for types. This attribute 412allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU 413Language Extensions Specification. It is intended to support the 414<code>__vector</code> keyword. 415 416 </body></html> 417 418