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