From: Sandra Loosemore Date: Mon, 4 May 2015 02:41:10 +0000 (-0400) Subject: extend.texi (Variable Attributes, [...]): Move sections up in file, to immediately... X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=6cefc5041cbdde0a7390327432ce1251ea674d75;p=gcc.git extend.texi (Variable Attributes, [...]): Move sections up in file, to immediately after the Function Attributes section. 2015-05-03 Sandra Loosemore gcc/ * doc/extend.texi (Variable Attributes, Type Attributes): Move sections up in file, to immediately after the Function Attributes section. From-SVN: r222758 --- diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 38ed17754f7..0a0179d1dd6 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,9 @@ +2015-05-03 Sandra Loosemore + + * doc/extend.texi (Variable Attributes, Type Attributes): Move + sections up in file, to immediately after the Function Attributes + section. + 2015-05-02 Jan Hubicka * tree.c (verify_type): Check various uses of TYPE_MINVAL. diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 1f6bbd539a8..db5a65b927b 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -4998,1651 +4998,1651 @@ function entry and exit sequences suitable for use in an interrupt handler when this attribute is present. @end table -@node Label Attributes -@section Label Attributes -@cindex Label Attributes +@node Variable Attributes +@section Specifying Attributes of Variables +@cindex attribute of variables +@cindex variable attributes -GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for -details of the exact syntax for using attributes. Other attributes are -available for functions (@pxref{Function Attributes}), variables -(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}). +The keyword @code{__attribute__} allows you to specify special +attributes of variables or structure fields. This keyword is followed +by an attribute specification inside double parentheses. Some +attributes are currently defined generically for variables. +Other attributes are defined for variables on particular target +systems. Other attributes are available for functions +(@pxref{Function Attributes}), labels (@pxref{Label Attributes}) and for +types (@pxref{Type Attributes}). +Other front ends might define more attributes +(@pxref{C++ Extensions,,Extensions to the C++ Language}). -This example uses the @code{cold} label attribute to indicate the -@code{ErrorHandling} branch is unlikely to be taken and that the -@code{ErrorHandling} label is unused: +@xref{Attribute Syntax}, for details of the exact syntax for using +attributes. -@smallexample +@menu +* Common Variable Attributes:: +* AVR Variable Attributes:: +* Blackfin Variable Attributes:: +* H8/300 Variable Attributes:: +* IA-64 Variable Attributes:: +* M32R/D Variable Attributes:: +* MeP Variable Attributes:: +* Microsoft Windows Variable Attributes:: +* PowerPC Variable Attributes:: +* SPU Variable Attributes:: +* x86 Variable Attributes:: +* Xstormy16 Variable Attributes:: +@end menu - asm goto ("some asm" : : : : NoError); +@node Common Variable Attributes +@subsection Common Variable Attributes -/* This branch (the fall-through from the asm) is less commonly used */ -ErrorHandling: - __attribute__((cold, unused)); /* Semi-colon is required here */ - printf("error\n"); - return 0; +The following attributes are supported on most targets. -NoError: - printf("no error\n"); - return 1; +@table @code +@cindex @code{aligned} variable attribute +@item aligned (@var{alignment}) +This attribute specifies a minimum alignment for the variable or +structure field, measured in bytes. For example, the declaration: + +@smallexample +int x __attribute__ ((aligned (16))) = 0; @end smallexample -@table @code -@item unused -@cindex @code{unused} label attribute -This feature is intended for program-generated code that may contain -unused labels, but which is compiled with @option{-Wall}. It is -not normally appropriate to use in it human-written code, though it -could be useful in cases where the code that jumps to the label is -contained within an @code{#ifdef} conditional. +@noindent +causes the compiler to allocate the global variable @code{x} on a +16-byte boundary. On a 68040, this could be used in conjunction with +an @code{asm} expression to access the @code{move16} instruction which +requires 16-byte aligned operands. -@item hot -@cindex @code{hot} label attribute -The @code{hot} attribute on a label is used to inform the compiler that -the path following the label is more likely than paths that are not so -annotated. This attribute is used in cases where @code{__builtin_expect} -cannot be used, for instance with computed goto or @code{asm goto}. +You can also specify the alignment of structure fields. For example, to +create a double-word aligned @code{int} pair, you could write: -@item cold -@cindex @code{cold} label attribute -The @code{cold} attribute on labels is used to inform the compiler that -the path following the label is unlikely to be executed. This attribute -is used in cases where @code{__builtin_expect} cannot be used, for instance -with computed goto or @code{asm goto}. +@smallexample +struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; +@end smallexample -@end table +@noindent +This is an alternative to creating a union with a @code{double} member, +which forces the union to be double-word aligned. -@node Attribute Syntax -@section Attribute Syntax -@cindex attribute syntax +As in the preceding examples, you can explicitly specify the alignment +(in bytes) that you wish the compiler to use for a given variable or +structure field. Alternatively, you can leave out the alignment factor +and just ask the compiler to align a variable or field to the +default alignment for the target architecture you are compiling for. +The default alignment is sufficient for all scalar types, but may not be +enough for all vector types on a target that supports vector operations. +The default alignment is fixed for a particular target ABI. -This section describes the syntax with which @code{__attribute__} may be -used, and the constructs to which attribute specifiers bind, for the C -language. Some details may vary for C++ and Objective-C@. Because of -infelicities in the grammar for attributes, some forms described here -may not be successfully parsed in all cases. +GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, +which is the largest alignment ever used for any data type on the +target machine you are compiling for. For example, you could write: -There are some problems with the semantics of attributes in C++. For -example, there are no manglings for attributes, although they may affect -code generation, so problems may arise when attributed types are used in -conjunction with templates or overloading. Similarly, @code{typeid} -does not distinguish between types with different attributes. Support -for attributes in C++ may be restricted in future to attributes on -declarations only, but not on nested declarators. +@smallexample +short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); +@end smallexample -@xref{Function Attributes}, for details of the semantics of attributes -applying to functions. @xref{Variable Attributes}, for details of the -semantics of attributes applying to variables. @xref{Type Attributes}, -for details of the semantics of attributes applying to structure, union -and enumerated types. -@xref{Label Attributes}, for details of the semantics of attributes -applying to labels. +The compiler automatically sets the alignment for the declared +variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can +often make copy operations more efficient, because the compiler can +use whatever instructions copy the biggest chunks of memory when +performing copies to or from the variables or fields that you have +aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} +may change depending on command-line options. -An @dfn{attribute specifier} is of the form -@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} -is a possibly empty comma-separated sequence of @dfn{attributes}, where -each attribute is one of the following: +When used on a struct, or struct member, the @code{aligned} attribute can +only increase the alignment; in order to decrease it, the @code{packed} +attribute must be specified as well. When used as part of a typedef, the +@code{aligned} attribute can both increase and decrease alignment, and +specifying the @code{packed} attribute generates a warning. -@itemize @bullet -@item -Empty. Empty attributes are ignored. +Note that the effectiveness of @code{aligned} attributes may be limited +by inherent limitations in your linker. On many systems, the linker is +only able to arrange for variables to be aligned up to a certain maximum +alignment. (For some linkers, the maximum supported alignment may +be very very small.) If your linker is only able to align variables +up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} +in an @code{__attribute__} still only provides you with 8-byte +alignment. See your linker documentation for further information. -@item -An attribute name -(which may be an identifier such as @code{unused}, or a reserved -word such as @code{const}). +The @code{aligned} attribute can also be used for functions +(@pxref{Common Function Attributes}.) -@item -An attribute name followed by a parenthesized list of -parameters for the attribute. -These parameters take one of the following forms: +@item cleanup (@var{cleanup_function}) +@cindex @code{cleanup} variable attribute +The @code{cleanup} attribute runs a function when the variable goes +out of scope. This attribute can only be applied to auto function +scope variables; it may not be applied to parameters or variables +with static storage duration. The function must take one parameter, +a pointer to a type compatible with the variable. The return value +of the function (if any) is ignored. -@itemize @bullet -@item -An identifier. For example, @code{mode} attributes use this form. +If @option{-fexceptions} is enabled, then @var{cleanup_function} +is run during the stack unwinding that happens during the +processing of the exception. Note that the @code{cleanup} attribute +does not allow the exception to be caught, only to perform an action. +It is undefined what happens if @var{cleanup_function} does not +return normally. -@item -An identifier followed by a comma and a non-empty comma-separated list -of expressions. For example, @code{format} attributes use this form. +@item common +@itemx nocommon +@cindex @code{common} variable attribute +@cindex @code{nocommon} variable attribute +@opindex fcommon +@opindex fno-common +The @code{common} attribute requests GCC to place a variable in +``common'' storage. The @code{nocommon} attribute requests the +opposite---to allocate space for it directly. -@item -A possibly empty comma-separated list of expressions. For example, -@code{format_arg} attributes use this form with the list being a single -integer constant expression, and @code{alias} attributes use this form -with the list being a single string constant. -@end itemize -@end itemize +These attributes override the default chosen by the +@option{-fno-common} and @option{-fcommon} flags respectively. -An @dfn{attribute specifier list} is a sequence of one or more attribute -specifiers, not separated by any other tokens. +@item deprecated +@itemx deprecated (@var{msg}) +@cindex @code{deprecated} variable attribute +The @code{deprecated} attribute results in a warning if the variable +is used anywhere in the source file. This is useful when identifying +variables that are expected to be removed in a future version of a +program. The warning also includes the location of the declaration +of the deprecated variable, to enable users to easily find further +information about why the variable is deprecated, or what they should +do instead. Note that the warning only occurs for uses: -You may optionally specify attribute names with @samp{__} -preceding and following the name. -This allows you to use them in header files without -being concerned about a possible macro of the same name. For example, -you may use the attribute name @code{__noreturn__} instead of @code{noreturn}. +@smallexample +extern int old_var __attribute__ ((deprecated)); +extern int old_var; +int new_fn () @{ return old_var; @} +@end smallexample +@noindent +results in a warning on line 3 but not line 2. The optional @var{msg} +argument, which must be a string, is printed in the warning if +present. -@subsubheading Label Attributes +The @code{deprecated} attribute can also be used for functions and +types (@pxref{Common Function Attributes}, +@pxref{Common Type Attributes}). -In GNU C, an attribute specifier list may appear after the colon following a -label, other than a @code{case} or @code{default} label. GNU C++ only permits -attributes on labels if the attribute specifier is immediately -followed by a semicolon (i.e., the label applies to an empty -statement). If the semicolon is missing, C++ label attributes are -ambiguous, as it is permissible for a declaration, which could begin -with an attribute list, to be labelled in C++. Declarations cannot be -labelled in C90 or C99, so the ambiguity does not arise there. +@item mode (@var{mode}) +@cindex @code{mode} variable attribute +This attribute specifies the data type for the declaration---whichever +type corresponds to the mode @var{mode}. This in effect lets you +request an integer or floating-point type according to its width. -@subsubheading Type Attributes +You may also specify a mode of @code{byte} or @code{__byte__} to +indicate the mode corresponding to a one-byte integer, @code{word} or +@code{__word__} for the mode of a one-word integer, and @code{pointer} +or @code{__pointer__} for the mode used to represent pointers. -An attribute specifier list may appear as part of a @code{struct}, -@code{union} or @code{enum} specifier. It may go either immediately -after the @code{struct}, @code{union} or @code{enum} keyword, or after -the closing brace. The former syntax is preferred. -Where attribute specifiers follow the closing brace, they are considered -to relate to the structure, union or enumerated type defined, not to any -enclosing declaration the type specifier appears in, and the type -defined is not complete until after the attribute specifiers. -@c Otherwise, there would be the following problems: a shift/reduce -@c conflict between attributes binding the struct/union/enum and -@c binding to the list of specifiers/qualifiers; and "aligned" -@c attributes could use sizeof for the structure, but the size could be -@c changed later by "packed" attributes. +@item packed +@cindex @code{packed} variable attribute +The @code{packed} attribute specifies that a variable or structure field +should have the smallest possible alignment---one byte for a variable, +and one bit for a field, unless you specify a larger value with the +@code{aligned} attribute. +Here is a structure in which the field @code{x} is packed, so that it +immediately follows @code{a}: -@subsubheading All other attributes +@smallexample +struct foo +@{ + char a; + int x[2] __attribute__ ((packed)); +@}; +@end smallexample -Otherwise, an attribute specifier appears as part of a declaration, -counting declarations of unnamed parameters and type names, and relates -to that declaration (which may be nested in another declaration, for -example in the case of a parameter declaration), or to a particular declarator -within a declaration. Where an -attribute specifier is applied to a parameter declared as a function or -an array, it should apply to the function or array rather than the -pointer to which the parameter is implicitly converted, but this is not -yet correctly implemented. +@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the +@code{packed} attribute on bit-fields of type @code{char}. This has +been fixed in GCC 4.4 but the change can lead to differences in the +structure layout. See the documentation of +@option{-Wpacked-bitfield-compat} for more information. -Any list of specifiers and qualifiers at the start of a declaration may -contain attribute specifiers, whether or not such a list may in that -context contain storage class specifiers. (Some attributes, however, -are essentially in the nature of storage class specifiers, and only make -sense where storage class specifiers may be used; for example, -@code{section}.) There is one necessary limitation to this syntax: the -first old-style parameter declaration in a function definition cannot -begin with an attribute specifier, because such an attribute applies to -the function instead by syntax described below (which, however, is not -yet implemented in this case). In some other cases, attribute -specifiers are permitted by this grammar but not yet supported by the -compiler. All attribute specifiers in this place relate to the -declaration as a whole. In the obsolescent usage where a type of -@code{int} is implied by the absence of type specifiers, such a list of -specifiers and qualifiers may be an attribute specifier list with no -other specifiers or qualifiers. +@item section ("@var{section-name}") +@cindex @code{section} variable attribute +Normally, the compiler places the objects it generates in sections like +@code{data} and @code{bss}. Sometimes, however, you need additional sections, +or you need certain particular variables to appear in special sections, +for example to map to special hardware. The @code{section} +attribute specifies that a variable (or function) lives in a particular +section. For example, this small program uses several specific section names: -At present, the first parameter in a function prototype must have some -type specifier that is not an attribute specifier; this resolves an -ambiguity in the interpretation of @code{void f(int -(__attribute__((foo)) x))}, but is subject to change. At present, if -the parentheses of a function declarator contain only attributes then -those attributes are ignored, rather than yielding an error or warning -or implying a single parameter of type int, but this is subject to -change. +@smallexample +struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; +struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; +char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; +int init_data __attribute__ ((section ("INITDATA"))); -An attribute specifier list may appear immediately before a declarator -(other than the first) in a comma-separated list of declarators in a -declaration of more than one identifier using a single list of -specifiers and qualifiers. Such attribute specifiers apply -only to the identifier before whose declarator they appear. For -example, in +main() +@{ + /* @r{Initialize stack pointer} */ + init_sp (stack + sizeof (stack)); -@smallexample -__attribute__((noreturn)) void d0 (void), - __attribute__((format(printf, 1, 2))) d1 (const char *, ...), - d2 (void); + /* @r{Initialize initialized data} */ + memcpy (&init_data, &data, &edata - &data); + + /* @r{Turn on the serial ports} */ + init_duart (&a); + init_duart (&b); +@} @end smallexample @noindent -the @code{noreturn} attribute applies to all the functions -declared; the @code{format} attribute only applies to @code{d1}. +Use the @code{section} attribute with +@emph{global} variables and not @emph{local} variables, +as shown in the example. -An attribute specifier list may appear immediately before the comma, -@code{=} or semicolon terminating the declaration of an identifier other -than a function definition. Such attribute specifiers apply -to the declared object or function. Where an -assembler name for an object or function is specified (@pxref{Asm -Labels}), the attribute must follow the @code{asm} -specification. +You may use the @code{section} attribute with initialized or +uninitialized global variables but the linker requires +each object be defined once, with the exception that uninitialized +variables tentatively go in the @code{common} (or @code{bss}) section +and can be multiply ``defined''. Using the @code{section} attribute +changes what section the variable goes into and may cause the +linker to issue an error if an uninitialized variable has multiple +definitions. You can force a variable to be initialized with the +@option{-fno-common} flag or the @code{nocommon} attribute. -An attribute specifier list may, in future, be permitted to appear after -the declarator in a function definition (before any old-style parameter -declarations or the function body). +Some file formats do not support arbitrary sections so the @code{section} +attribute is not available on all platforms. +If you need to map the entire contents of a module to a particular +section, consider using the facilities of the linker instead. -Attribute specifiers may be mixed with type qualifiers appearing inside -the @code{[]} of a parameter array declarator, in the C99 construct by -which such qualifiers are applied to the pointer to which the array is -implicitly converted. Such attribute specifiers apply to the pointer, -not to the array, but at present this is not implemented and they are -ignored. +@item tls_model ("@var{tls_model}") +@cindex @code{tls_model} variable attribute +The @code{tls_model} attribute sets thread-local storage model +(@pxref{Thread-Local}) of a particular @code{__thread} variable, +overriding @option{-ftls-model=} command-line switch on a per-variable +basis. +The @var{tls_model} argument should be one of @code{global-dynamic}, +@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. -An attribute specifier list may appear at the start of a nested -declarator. At present, there are some limitations in this usage: the -attributes correctly apply to the declarator, but for most individual -attributes the semantics this implies are not implemented. -When attribute specifiers follow the @code{*} of a pointer -declarator, they may be mixed with any type qualifiers present. -The following describes the formal semantics of this syntax. It makes the -most sense if you are familiar with the formal specification of -declarators in the ISO C standard. +Not all targets support this attribute. -Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T -D1}, where @code{T} contains declaration specifiers that specify a type -@var{Type} (such as @code{int}) and @code{D1} is a declarator that -contains an identifier @var{ident}. The type specified for @var{ident} -for derived declarators whose type does not include an attribute -specifier is as in the ISO C standard. +@item unused +@cindex @code{unused} variable attribute +This attribute, attached to a variable, means that the variable is meant +to be possibly unused. GCC does not produce a warning for this +variable. -If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, -and the declaration @code{T D} specifies the type -``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then -@code{T D1} specifies the type ``@var{derived-declarator-type-list} -@var{attribute-specifier-list} @var{Type}'' for @var{ident}. +@item used +@cindex @code{used} variable attribute +This attribute, attached to a variable with static storage, means that +the variable must be emitted even if it appears that the variable is not +referenced. -If @code{D1} has the form @code{* -@var{type-qualifier-and-attribute-specifier-list} D}, and the -declaration @code{T D} specifies the type -``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then -@code{T D1} specifies the type ``@var{derived-declarator-type-list} -@var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for -@var{ident}. +When applied to a static data member of a C++ class template, the +attribute also means that the member is instantiated if the +class itself is instantiated. -For example, +@item vector_size (@var{bytes}) +@cindex @code{vector_size} variable attribute +This attribute specifies the vector size for the variable, measured in +bytes. For example, the declaration: @smallexample -void (__attribute__((noreturn)) ****f) (void); +int foo __attribute__ ((vector_size (16))); @end smallexample @noindent -specifies the type ``pointer to pointer to pointer to pointer to -non-returning function returning @code{void}''. As another example, +causes the compiler to set the mode for @code{foo}, to be 16 bytes, +divided into @code{int} sized units. Assuming a 32-bit int (a vector of +4 units of 4 bytes), the corresponding mode of @code{foo} is V4SI@. + +This attribute is only applicable to integral and float scalars, +although arrays, pointers, and function return values are allowed in +conjunction with this construct. + +Aggregates with this attribute are invalid, even if they are of the same +size as a corresponding scalar. For example, the declaration: @smallexample -char *__attribute__((aligned(8))) *f; +struct S @{ int a; @}; +struct S __attribute__ ((vector_size (16))) foo; @end smallexample @noindent -specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. -Note again that this does not work with most attributes; for example, -the usage of @samp{aligned} and @samp{noreturn} attributes given above -is not yet supported. +is invalid even if the size of the structure is the same as the size of +the @code{int}. -For compatibility with existing code written for compiler versions that -did not implement attributes on nested declarators, some laxity is -allowed in the placing of attributes. If an attribute that only applies -to types is applied to a declaration, it is treated as applying to -the type of that declaration. If an attribute that only applies to -declarations is applied to the type of a declaration, it is treated -as applying to that declaration; and, for compatibility with code -placing the attributes immediately before the identifier declared, such -an attribute applied to a function return type is treated as -applying to the function type, and such an attribute applied to an array -element type is treated as applying to the array type. If an -attribute that only applies to function types is applied to a -pointer-to-function type, it is treated as applying to the pointer -target type; if such an attribute is applied to a function return type -that is not a pointer-to-function type, it is treated as applying -to the function type. +@item weak +@cindex @code{weak} variable attribute +The @code{weak} attribute is described in +@ref{Common Function Attributes}. -@node Function Prototypes -@section Prototypes and Old-Style Function Definitions -@cindex function prototype declarations -@cindex old-style function definitions -@cindex promotion of formal parameters +@end table -GNU C extends ISO C to allow a function prototype to override a later -old-style non-prototype definition. Consider the following example: +@node AVR Variable Attributes +@subsection AVR Variable Attributes -@smallexample -/* @r{Use prototypes unless the compiler is old-fashioned.} */ -#ifdef __STDC__ -#define P(x) x -#else -#define P(x) () -#endif +@table @code +@item progmem +@cindex @code{progmem} variable attribute, AVR +The @code{progmem} attribute is used on the AVR to place read-only +data in the non-volatile program memory (flash). The @code{progmem} +attribute accomplishes this by putting respective variables into a +section whose name starts with @code{.progmem}. -/* @r{Prototype function declaration.} */ -int isroot P((uid_t)); +This attribute works similar to the @code{section} attribute +but adds additional checking. Notice that just like the +@code{section} attribute, @code{progmem} affects the location +of the data but not how this data is accessed. -/* @r{Old-style function definition.} */ -int -isroot (x) /* @r{??? lossage here ???} */ - uid_t x; +In order to read data located with the @code{progmem} attribute +(inline) assembler must be used. +@smallexample +/* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */ +#include + +/* Locate var in flash memory */ +const int var[2] PROGMEM = @{ 1, 2 @}; + +int read_var (int i) @{ - return x == 0; + /* Access var[] by accessor macro from avr/pgmspace.h */ + return (int) pgm_read_word (& var[i]); @} @end smallexample -Suppose the type @code{uid_t} happens to be @code{short}. ISO C does -not allow this example, because subword arguments in old-style -non-prototype definitions are promoted. Therefore in this example the -function definition's argument is really an @code{int}, which does not -match the prototype argument type of @code{short}. +AVR is a Harvard architecture processor and data and read-only data +normally resides in the data memory (RAM). -This restriction of ISO C makes it hard to write code that is portable -to traditional C compilers, because the programmer does not know -whether the @code{uid_t} type is @code{short}, @code{int}, or -@code{long}. Therefore, in cases like these GNU C allows a prototype -to override a later old-style definition. More precisely, in GNU C, a -function prototype argument type overrides the argument type specified -by a later old-style definition if the former type is the same as the -latter type before promotion. Thus in GNU C the above example is -equivalent to the following: +See also the @ref{AVR Named Address Spaces} section for +an alternate way to locate and access data in flash memory. -@smallexample -int isroot (uid_t); +@item io +@itemx io (@var{addr}) +@cindex @code{io} variable attribute, AVR +Variables with the @code{io} attribute are used to address +memory-mapped peripherals in the io address range. +If an address is specified, the variable +is assigned that address, and the value is interpreted as an +address in the data address space. +Example: -int -isroot (uid_t x) -@{ - return x == 0; -@} +@smallexample +volatile int porta __attribute__((io (0x22))); @end smallexample -@noindent -GNU C++ does not support old-style function definitions, so this -extension is irrelevant. +The address specified in the address in the data address range. -@node C++ Comments -@section C++ Style Comments -@cindex @code{//} -@cindex C++ comments -@cindex comments, C++ style +Otherwise, the variable it is not assigned an address, but the +compiler will still use in/out instructions where applicable, +assuming some other module assigns an address in the io address range. +Example: -In GNU C, you may use C++ style comments, which start with @samp{//} and -continue until the end of the line. Many other C implementations allow -such comments, and they are included in the 1999 C standard. However, -C++ style comments are not recognized if you specify an @option{-std} -option specifying a version of ISO C before C99, or @option{-ansi} -(equivalent to @option{-std=c90}). +@smallexample +extern volatile int porta __attribute__((io)); +@end smallexample -@node Dollar Signs -@section Dollar Signs in Identifier Names -@cindex $ -@cindex dollar signs in identifier names -@cindex identifier names, dollar signs in +@item io_low +@itemx io_low (@var{addr}) +@cindex @code{io_low} variable attribute, AVR +This is like the @code{io} attribute, but additionally it informs the +compiler that the object lies in the lower half of the I/O area, +allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis} +instructions. -In GNU C, you may normally use dollar signs in identifier names. -This is because many traditional C implementations allow such identifiers. -However, dollar signs in identifiers are not supported on a few target -machines, typically because the target assembler does not allow them. +@item address +@itemx address (@var{addr}) +@cindex @code{address} variable attribute, AVR +Variables with the @code{address} attribute are used to address +memory-mapped peripherals that may lie outside the io address range. -@node Character Escapes -@section The Character @key{ESC} in Constants +@smallexample +volatile int porta __attribute__((address (0x600))); +@end smallexample -You can use the sequence @samp{\e} in a string or character constant to -stand for the ASCII character @key{ESC}. +@end table -@node Variable Attributes -@section Specifying Attributes of Variables -@cindex attribute of variables -@cindex variable attributes +@node Blackfin Variable Attributes +@subsection Blackfin Variable Attributes -The keyword @code{__attribute__} allows you to specify special -attributes of variables or structure fields. This keyword is followed -by an attribute specification inside double parentheses. Some -attributes are currently defined generically for variables. -Other attributes are defined for variables on particular target -systems. Other attributes are available for functions -(@pxref{Function Attributes}), labels (@pxref{Label Attributes}) and for -types (@pxref{Type Attributes}). -Other front ends might define more attributes -(@pxref{C++ Extensions,,Extensions to the C++ Language}). +Three attributes are currently defined for the Blackfin. -@xref{Attribute Syntax}, for details of the exact syntax for using -attributes. +@table @code +@item l1_data +@itemx l1_data_A +@itemx l1_data_B +@cindex @code{l1_data} variable attribute, Blackfin +@cindex @code{l1_data_A} variable attribute, Blackfin +@cindex @code{l1_data_B} variable attribute, Blackfin +Use these attributes on the Blackfin to place the variable into L1 Data SRAM. +Variables with @code{l1_data} attribute are put into the specific section +named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into +the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} +attribute are put into the specific section named @code{.l1.data.B}. -@menu -* Common Variable Attributes:: -* AVR Variable Attributes:: -* Blackfin Variable Attributes:: -* H8/300 Variable Attributes:: -* IA-64 Variable Attributes:: -* M32R/D Variable Attributes:: -* MeP Variable Attributes:: -* Microsoft Windows Variable Attributes:: -* PowerPC Variable Attributes:: -* SPU Variable Attributes:: -* x86 Variable Attributes:: -* Xstormy16 Variable Attributes:: -@end menu +@item l2 +@cindex @code{l2} variable attribute, Blackfin +Use this attribute on the Blackfin to place the variable into L2 SRAM. +Variables with @code{l2} attribute are put into the specific section +named @code{.l2.data}. +@end table -@node Common Variable Attributes -@subsection Common Variable Attributes +@node H8/300 Variable Attributes +@subsection H8/300 Variable Attributes -The following attributes are supported on most targets. +These variable attributes are available for H8/300 targets: @table @code -@cindex @code{aligned} variable attribute -@item aligned (@var{alignment}) -This attribute specifies a minimum alignment for the variable or -structure field, measured in bytes. For example, the declaration: - -@smallexample -int x __attribute__ ((aligned (16))) = 0; -@end smallexample +@item eightbit_data +@cindex @code{eightbit_data} variable attribute, H8/300 +@cindex eight-bit data on the H8/300, H8/300H, and H8S +Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified +variable should be placed into the eight-bit data section. +The compiler generates more efficient code for certain operations +on data in the eight-bit data area. Note the eight-bit data area is limited to +256 bytes of data. -@noindent -causes the compiler to allocate the global variable @code{x} on a -16-byte boundary. On a 68040, this could be used in conjunction with -an @code{asm} expression to access the @code{move16} instruction which -requires 16-byte aligned operands. +You must use GAS and GLD from GNU binutils version 2.7 or later for +this attribute to work correctly. -You can also specify the alignment of structure fields. For example, to -create a double-word aligned @code{int} pair, you could write: +@item tiny_data +@cindex @code{tiny_data} variable attribute, H8/300 +@cindex tiny data section on the H8/300H and H8S +Use this attribute on the H8/300H and H8S to indicate that the specified +variable should be placed into the tiny data section. +The compiler generates more efficient code for loads and stores +on data in the tiny data section. Note the tiny data area is limited to +slightly under 32KB of data. -@smallexample -struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; -@end smallexample +@end table -@noindent -This is an alternative to creating a union with a @code{double} member, -which forces the union to be double-word aligned. +@node IA-64 Variable Attributes +@subsection IA-64 Variable Attributes -As in the preceding examples, you can explicitly specify the alignment -(in bytes) that you wish the compiler to use for a given variable or -structure field. Alternatively, you can leave out the alignment factor -and just ask the compiler to align a variable or field to the -default alignment for the target architecture you are compiling for. -The default alignment is sufficient for all scalar types, but may not be -enough for all vector types on a target that supports vector operations. -The default alignment is fixed for a particular target ABI. +The IA-64 back end supports the following variable attribute: -GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, -which is the largest alignment ever used for any data type on the -target machine you are compiling for. For example, you could write: +@table @code +@item model (@var{model-name}) +@cindex @code{model} variable attribute, IA-64 -@smallexample -short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); -@end smallexample +On IA-64, use this attribute to set the addressability of an object. +At present, the only supported identifier for @var{model-name} is +@code{small}, indicating addressability via ``small'' (22-bit) +addresses (so that their addresses can be loaded with the @code{addl} +instruction). Caveat: such addressing is by definition not position +independent and hence this attribute must not be used for objects +defined by shared libraries. -The compiler automatically sets the alignment for the declared -variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can -often make copy operations more efficient, because the compiler can -use whatever instructions copy the biggest chunks of memory when -performing copies to or from the variables or fields that you have -aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} -may change depending on command-line options. +@end table -When used on a struct, or struct member, the @code{aligned} attribute can -only increase the alignment; in order to decrease it, the @code{packed} -attribute must be specified as well. When used as part of a typedef, the -@code{aligned} attribute can both increase and decrease alignment, and -specifying the @code{packed} attribute generates a warning. +@node M32R/D Variable Attributes +@subsection M32R/D Variable Attributes -Note that the effectiveness of @code{aligned} attributes may be limited -by inherent limitations in your linker. On many systems, the linker is -only able to arrange for variables to be aligned up to a certain maximum -alignment. (For some linkers, the maximum supported alignment may -be very very small.) If your linker is only able to align variables -up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} -in an @code{__attribute__} still only provides you with 8-byte -alignment. See your linker documentation for further information. +One attribute is currently defined for the M32R/D@. -The @code{aligned} attribute can also be used for functions -(@pxref{Common Function Attributes}.) +@table @code +@item model (@var{model-name}) +@cindex @code{model-name} variable attribute, M32R/D +@cindex variable addressability on the M32R/D +Use this attribute on the M32R/D to set the addressability of an object. +The identifier @var{model-name} is one of @code{small}, @code{medium}, +or @code{large}, representing each of the code models. -@item cleanup (@var{cleanup_function}) -@cindex @code{cleanup} variable attribute -The @code{cleanup} attribute runs a function when the variable goes -out of scope. This attribute can only be applied to auto function -scope variables; it may not be applied to parameters or variables -with static storage duration. The function must take one parameter, -a pointer to a type compatible with the variable. The return value -of the function (if any) is ignored. +Small model objects live in the lower 16MB of memory (so that their +addresses can be loaded with the @code{ld24} instruction). -If @option{-fexceptions} is enabled, then @var{cleanup_function} -is run during the stack unwinding that happens during the -processing of the exception. Note that the @code{cleanup} attribute -does not allow the exception to be caught, only to perform an action. -It is undefined what happens if @var{cleanup_function} does not -return normally. +Medium and large model objects may live anywhere in the 32-bit address space +(the compiler generates @code{seth/add3} instructions to load their +addresses). +@end table -@item common -@itemx nocommon -@cindex @code{common} variable attribute -@cindex @code{nocommon} variable attribute -@opindex fcommon -@opindex fno-common -The @code{common} attribute requests GCC to place a variable in -``common'' storage. The @code{nocommon} attribute requests the -opposite---to allocate space for it directly. +@node MeP Variable Attributes +@subsection MeP Variable Attributes -These attributes override the default chosen by the -@option{-fno-common} and @option{-fcommon} flags respectively. +The MeP target has a number of addressing modes and busses. The +@code{near} space spans the standard memory space's first 16 megabytes +(24 bits). The @code{far} space spans the entire 32-bit memory space. +The @code{based} space is a 128-byte region in the memory space that +is addressed relative to the @code{$tp} register. The @code{tiny} +space is a 65536-byte region relative to the @code{$gp} register. In +addition to these memory regions, the MeP target has a separate 16-bit +control bus which is specified with @code{cb} attributes. -@item deprecated -@itemx deprecated (@var{msg}) -@cindex @code{deprecated} variable attribute -The @code{deprecated} attribute results in a warning if the variable -is used anywhere in the source file. This is useful when identifying -variables that are expected to be removed in a future version of a -program. The warning also includes the location of the declaration -of the deprecated variable, to enable users to easily find further -information about why the variable is deprecated, or what they should -do instead. Note that the warning only occurs for uses: +@table @code -@smallexample -extern int old_var __attribute__ ((deprecated)); -extern int old_var; -int new_fn () @{ return old_var; @} -@end smallexample +@item based +@cindex @code{based} variable attribute, MeP +Any variable with the @code{based} attribute is assigned to the +@code{.based} section, and is accessed with relative to the +@code{$tp} register. -@noindent -results in a warning on line 3 but not line 2. The optional @var{msg} -argument, which must be a string, is printed in the warning if -present. +@item tiny +@cindex @code{tiny} variable attribute, MeP +Likewise, the @code{tiny} attribute assigned variables to the +@code{.tiny} section, relative to the @code{$gp} register. -The @code{deprecated} attribute can also be used for functions and -types (@pxref{Common Function Attributes}, -@pxref{Common Type Attributes}). +@item near +@cindex @code{near} variable attribute, MeP +Variables with the @code{near} attribute are assumed to have addresses +that fit in a 24-bit addressing mode. This is the default for large +variables (@code{-mtiny=4} is the default) but this attribute can +override @code{-mtiny=} for small variables, or override @code{-ml}. -@item mode (@var{mode}) -@cindex @code{mode} variable attribute -This attribute specifies the data type for the declaration---whichever -type corresponds to the mode @var{mode}. This in effect lets you -request an integer or floating-point type according to its width. +@item far +@cindex @code{far} variable attribute, MeP +Variables with the @code{far} attribute are addressed using a full +32-bit address. Since this covers the entire memory space, this +allows modules to make no assumptions about where variables might be +stored. -You may also specify a mode of @code{byte} or @code{__byte__} to -indicate the mode corresponding to a one-byte integer, @code{word} or -@code{__word__} for the mode of a one-word integer, and @code{pointer} -or @code{__pointer__} for the mode used to represent pointers. +@item io +@cindex @code{io} variable attribute, MeP +@itemx io (@var{addr}) +Variables with the @code{io} attribute are used to address +memory-mapped peripherals. If an address is specified, the variable +is assigned that address, else it is not assigned an address (it is +assumed some other module assigns an address). Example: -@item packed -@cindex @code{packed} variable attribute -The @code{packed} attribute specifies that a variable or structure field -should have the smallest possible alignment---one byte for a variable, -and one bit for a field, unless you specify a larger value with the -@code{aligned} attribute. +@smallexample +int timer_count __attribute__((io(0x123))); +@end smallexample -Here is a structure in which the field @code{x} is packed, so that it -immediately follows @code{a}: +@item cb +@itemx cb (@var{addr}) +@cindex @code{cb} variable attribute, MeP +Variables with the @code{cb} attribute are used to access the control +bus, using special instructions. @code{addr} indicates the control bus +address. Example: @smallexample -struct foo -@{ - char a; - int x[2] __attribute__ ((packed)); -@}; +int cpu_clock __attribute__((cb(0x123))); @end smallexample -@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the -@code{packed} attribute on bit-fields of type @code{char}. This has -been fixed in GCC 4.4 but the change can lead to differences in the -structure layout. See the documentation of -@option{-Wpacked-bitfield-compat} for more information. +@end table -@item section ("@var{section-name}") -@cindex @code{section} variable attribute -Normally, the compiler places the objects it generates in sections like -@code{data} and @code{bss}. Sometimes, however, you need additional sections, -or you need certain particular variables to appear in special sections, -for example to map to special hardware. The @code{section} -attribute specifies that a variable (or function) lives in a particular -section. For example, this small program uses several specific section names: +@node Microsoft Windows Variable Attributes +@subsection Microsoft Windows Variable Attributes + +You can use these attributes on Microsoft Windows targets. +@ref{x86 Variable Attributes} for additional Windows compatibility +attributes available on all x86 targets. + +@table @code +@item dllimport +@itemx dllexport +@cindex @code{dllimport} variable attribute +@cindex @code{dllexport} variable attribute +The @code{dllimport} and @code{dllexport} attributes are described in +@ref{Microsoft Windows Function Attributes}. + +@item selectany +@cindex @code{selectany} variable attribute +The @code{selectany} attribute causes an initialized global variable to +have link-once semantics. When multiple definitions of the variable are +encountered by the linker, the first is selected and the remainder are +discarded. Following usage by the Microsoft compiler, the linker is told +@emph{not} to warn about size or content differences of the multiple +definitions. + +Although the primary usage of this attribute is for POD types, the +attribute can also be applied to global C++ objects that are initialized +by a constructor. In this case, the static initialization and destruction +code for the object is emitted in each translation defining the object, +but the calls to the constructor and destructor are protected by a +link-once guard variable. + +The @code{selectany} attribute is only available on Microsoft Windows +targets. You can use @code{__declspec (selectany)} as a synonym for +@code{__attribute__ ((selectany))} for compatibility with other +compilers. + +@item shared +@cindex @code{shared} variable attribute +On Microsoft Windows, in addition to putting variable definitions in a named +section, the section can also be shared among all running copies of an +executable or DLL@. For example, this small program defines shared data +by putting it in a named section @code{shared} and marking the section +shareable: @smallexample -struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; -struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; -char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; -int init_data __attribute__ ((section ("INITDATA"))); +int foo __attribute__((section ("shared"), shared)) = 0; +int main() @{ - /* @r{Initialize stack pointer} */ - init_sp (stack + sizeof (stack)); - - /* @r{Initialize initialized data} */ - memcpy (&init_data, &data, &edata - &data); - - /* @r{Turn on the serial ports} */ - init_duart (&a); - init_duart (&b); + /* @r{Read and write foo. All running + copies see the same value.} */ + return 0; @} @end smallexample @noindent -Use the @code{section} attribute with -@emph{global} variables and not @emph{local} variables, -as shown in the example. +You may only use the @code{shared} attribute along with @code{section} +attribute with a fully-initialized global definition because of the way +linkers work. See @code{section} attribute for more information. -You may use the @code{section} attribute with initialized or -uninitialized global variables but the linker requires -each object be defined once, with the exception that uninitialized -variables tentatively go in the @code{common} (or @code{bss}) section -and can be multiply ``defined''. Using the @code{section} attribute -changes what section the variable goes into and may cause the -linker to issue an error if an uninitialized variable has multiple -definitions. You can force a variable to be initialized with the -@option{-fno-common} flag or the @code{nocommon} attribute. +The @code{shared} attribute is only available on Microsoft Windows@. -Some file formats do not support arbitrary sections so the @code{section} -attribute is not available on all platforms. -If you need to map the entire contents of a module to a particular -section, consider using the facilities of the linker instead. +@end table -@item tls_model ("@var{tls_model}") -@cindex @code{tls_model} variable attribute -The @code{tls_model} attribute sets thread-local storage model -(@pxref{Thread-Local}) of a particular @code{__thread} variable, -overriding @option{-ftls-model=} command-line switch on a per-variable -basis. -The @var{tls_model} argument should be one of @code{global-dynamic}, -@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. +@node PowerPC Variable Attributes +@subsection PowerPC Variable Attributes -Not all targets support this attribute. +Three attributes currently are defined for PowerPC configurations: +@code{altivec}, @code{ms_struct} and @code{gcc_struct}. -@item unused -@cindex @code{unused} variable attribute -This attribute, attached to a variable, means that the variable is meant -to be possibly unused. GCC does not produce a warning for this -variable. +@cindex @code{ms_struct} variable attribute, PowerPC +@cindex @code{gcc_struct} variable attribute, PowerPC +For full documentation of the struct attributes please see the +documentation in @ref{x86 Variable Attributes}. -@item used -@cindex @code{used} variable attribute -This attribute, attached to a variable with static storage, means that -the variable must be emitted even if it appears that the variable is not -referenced. +@cindex @code{altivec} variable attribute, PowerPC +For documentation of @code{altivec} attribute please see the +documentation in @ref{PowerPC Type Attributes}. -When applied to a static data member of a C++ class template, the -attribute also means that the member is instantiated if the -class itself is instantiated. +@node SPU Variable Attributes +@subsection SPU Variable Attributes -@item vector_size (@var{bytes}) -@cindex @code{vector_size} variable attribute -This attribute specifies the vector size for the variable, measured in -bytes. For example, the declaration: +@cindex @code{spu_vector} variable attribute, SPU +The SPU supports the @code{spu_vector} attribute for variables. For +documentation of this attribute please see the documentation in +@ref{SPU Type Attributes}. -@smallexample -int foo __attribute__ ((vector_size (16))); -@end smallexample +@node x86 Variable Attributes +@subsection x86 Variable Attributes -@noindent -causes the compiler to set the mode for @code{foo}, to be 16 bytes, -divided into @code{int} sized units. Assuming a 32-bit int (a vector of -4 units of 4 bytes), the corresponding mode of @code{foo} is V4SI@. +Two attributes are currently defined for x86 configurations: +@code{ms_struct} and @code{gcc_struct}. -This attribute is only applicable to integral and float scalars, -although arrays, pointers, and function return values are allowed in -conjunction with this construct. +@table @code +@item ms_struct +@itemx gcc_struct +@cindex @code{ms_struct} variable attribute, x86 +@cindex @code{gcc_struct} variable attribute, x86 -Aggregates with this attribute are invalid, even if they are of the same -size as a corresponding scalar. For example, the declaration: +If @code{packed} is used on a structure, or if bit-fields are used, +it may be that the Microsoft ABI lays out the structure differently +than the way GCC normally does. Particularly when moving packed +data between functions compiled with GCC and the native Microsoft compiler +(either via function call or as data in a file), it may be necessary to access +either format. -@smallexample -struct S @{ int a; @}; -struct S __attribute__ ((vector_size (16))) foo; -@end smallexample +Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows x86 +compilers to match the native Microsoft compiler. -@noindent -is invalid even if the size of the structure is the same as the size of -the @code{int}. +The Microsoft structure layout algorithm is fairly simple with the exception +of the bit-field packing. +The padding and alignment of members of structures and whether a bit-field +can straddle a storage-unit boundary are determine by these rules: -@item weak -@cindex @code{weak} variable attribute -The @code{weak} attribute is described in -@ref{Common Function Attributes}. +@enumerate +@item Structure members are stored sequentially in the order in which they are +declared: the first member has the lowest memory address and the last member +the highest. -@end table +@item Every data object has an alignment requirement. The alignment requirement +for all data except structures, unions, and arrays is either the size of the +object or the current packing size (specified with either the +@code{aligned} attribute or the @code{pack} pragma), +whichever is less. For structures, unions, and arrays, +the alignment requirement is the largest alignment requirement of its members. +Every object is allocated an offset so that: -@node AVR Variable Attributes -@subsection AVR Variable Attributes +@smallexample +offset % alignment_requirement == 0 +@end smallexample -@table @code -@item progmem -@cindex @code{progmem} variable attribute, AVR -The @code{progmem} attribute is used on the AVR to place read-only -data in the non-volatile program memory (flash). The @code{progmem} -attribute accomplishes this by putting respective variables into a -section whose name starts with @code{.progmem}. +@item Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation +unit if the integral types are the same size and if the next bit-field fits +into the current allocation unit without crossing the boundary imposed by the +common alignment requirements of the bit-fields. +@end enumerate -This attribute works similar to the @code{section} attribute -but adds additional checking. Notice that just like the -@code{section} attribute, @code{progmem} affects the location -of the data but not how this data is accessed. +MSVC interprets zero-length bit-fields in the following ways: -In order to read data located with the @code{progmem} attribute -(inline) assembler must be used. -@smallexample -/* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */ -#include +@enumerate +@item If a zero-length bit-field is inserted between two bit-fields that +are normally coalesced, the bit-fields are not coalesced. -/* Locate var in flash memory */ -const int var[2] PROGMEM = @{ 1, 2 @}; +For example: -int read_var (int i) -@{ - /* Access var[] by accessor macro from avr/pgmspace.h */ - return (int) pgm_read_word (& var[i]); -@} +@smallexample +struct + @{ + unsigned long bf_1 : 12; + unsigned long : 0; + unsigned long bf_2 : 12; + @} t1; @end smallexample -AVR is a Harvard architecture processor and data and read-only data -normally resides in the data memory (RAM). +@noindent +The size of @code{t1} is 8 bytes with the zero-length bit-field. If the +zero-length bit-field were removed, @code{t1}'s size would be 4 bytes. -See also the @ref{AVR Named Address Spaces} section for -an alternate way to locate and access data in flash memory. +@item If a zero-length bit-field is inserted after a bit-field, @code{foo}, and the +alignment of the zero-length bit-field is greater than the member that follows it, +@code{bar}, @code{bar} is aligned as the type of the zero-length bit-field. -@item io -@itemx io (@var{addr}) -@cindex @code{io} variable attribute, AVR -Variables with the @code{io} attribute are used to address -memory-mapped peripherals in the io address range. -If an address is specified, the variable -is assigned that address, and the value is interpreted as an -address in the data address space. -Example: +For example: @smallexample -volatile int porta __attribute__((io (0x22))); +struct + @{ + char foo : 4; + short : 0; + char bar; + @} t2; + +struct + @{ + char foo : 4; + short : 0; + double bar; + @} t3; @end smallexample -The address specified in the address in the data address range. +@noindent +For @code{t2}, @code{bar} is placed at offset 2, rather than offset 1. +Accordingly, the size of @code{t2} is 4. For @code{t3}, the zero-length +bit-field does not affect the alignment of @code{bar} or, as a result, the size +of the structure. -Otherwise, the variable it is not assigned an address, but the -compiler will still use in/out instructions where applicable, -assuming some other module assigns an address in the io address range. -Example: +Taking this into account, it is important to note the following: + +@enumerate +@item If a zero-length bit-field follows a normal bit-field, the type of the +zero-length bit-field may affect the alignment of the structure as whole. For +example, @code{t2} has a size of 4 bytes, since the zero-length bit-field follows a +normal bit-field, and is of type short. + +@item Even if a zero-length bit-field is not followed by a normal bit-field, it may +still affect the alignment of the structure: @smallexample -extern volatile int porta __attribute__((io)); +struct + @{ + char foo : 6; + long : 0; + @} t4; @end smallexample -@item io_low -@itemx io_low (@var{addr}) -@cindex @code{io_low} variable attribute, AVR -This is like the @code{io} attribute, but additionally it informs the -compiler that the object lies in the lower half of the I/O area, -allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis} -instructions. +@noindent +Here, @code{t4} takes up 4 bytes. +@end enumerate -@item address -@itemx address (@var{addr}) -@cindex @code{address} variable attribute, AVR -Variables with the @code{address} attribute are used to address -memory-mapped peripherals that may lie outside the io address range. +@item Zero-length bit-fields following non-bit-field members are ignored: @smallexample -volatile int porta __attribute__((address (0x600))); +struct + @{ + char foo; + long : 0; + char bar; + @} t5; @end smallexample +@noindent +Here, @code{t5} takes up 2 bytes. +@end enumerate @end table -@node Blackfin Variable Attributes -@subsection Blackfin Variable Attributes +@node Xstormy16 Variable Attributes +@subsection Xstormy16 Variable Attributes -Three attributes are currently defined for the Blackfin. +One attribute is currently defined for xstormy16 configurations: +@code{below100}. @table @code -@item l1_data -@itemx l1_data_A -@itemx l1_data_B -@cindex @code{l1_data} variable attribute, Blackfin -@cindex @code{l1_data_A} variable attribute, Blackfin -@cindex @code{l1_data_B} variable attribute, Blackfin -Use these attributes on the Blackfin to place the variable into L1 Data SRAM. -Variables with @code{l1_data} attribute are put into the specific section -named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into -the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} -attribute are put into the specific section named @code{.l1.data.B}. +@item below100 +@cindex @code{below100} variable attribute, Xstormy16 + +If a variable has the @code{below100} attribute (@code{BELOW100} is +allowed also), GCC places the variable in the first 0x100 bytes of +memory and use special opcodes to access it. Such variables are +placed in either the @code{.bss_below100} section or the +@code{.data_below100} section. -@item l2 -@cindex @code{l2} variable attribute, Blackfin -Use this attribute on the Blackfin to place the variable into L2 SRAM. -Variables with @code{l2} attribute are put into the specific section -named @code{.l2.data}. @end table -@node H8/300 Variable Attributes -@subsection H8/300 Variable Attributes +@node Type Attributes +@section Specifying Attributes of Types +@cindex attribute of types +@cindex type attributes -These variable attributes are available for H8/300 targets: +The keyword @code{__attribute__} allows you to specify special +attributes of types. Some type attributes apply only to @code{struct} +and @code{union} types, while others can apply to any type defined +via a @code{typedef} declaration. Other attributes are defined for +functions (@pxref{Function Attributes}), labels (@pxref{Label +Attributes}) and for variables (@pxref{Variable Attributes}). -@table @code -@item eightbit_data -@cindex @code{eightbit_data} variable attribute, H8/300 -@cindex eight-bit data on the H8/300, H8/300H, and H8S -Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified -variable should be placed into the eight-bit data section. -The compiler generates more efficient code for certain operations -on data in the eight-bit data area. Note the eight-bit data area is limited to -256 bytes of data. +The @code{__attribute__} keyword is followed by an attribute specification +inside double parentheses. -You must use GAS and GLD from GNU binutils version 2.7 or later for -this attribute to work correctly. +You may specify type attributes in an enum, struct or union type +declaration or definition by placing them immediately after the +@code{struct}, @code{union} or @code{enum} keyword. A less preferred +syntax is to place them just past the closing curly brace of the +definition. -@item tiny_data -@cindex @code{tiny_data} variable attribute, H8/300 -@cindex tiny data section on the H8/300H and H8S -Use this attribute on the H8/300H and H8S to indicate that the specified -variable should be placed into the tiny data section. -The compiler generates more efficient code for loads and stores -on data in the tiny data section. Note the tiny data area is limited to -slightly under 32KB of data. +You can also include type attributes in a @code{typedef} declaration. +@xref{Attribute Syntax}, for details of the exact syntax for using +attributes. -@end table +@menu +* Common Type Attributes:: +* ARM Type Attributes:: +* MeP Type Attributes:: +* PowerPC Type Attributes:: +* SPU Type Attributes:: +* x86 Type Attributes:: +@end menu -@node IA-64 Variable Attributes -@subsection IA-64 Variable Attributes +@node Common Type Attributes +@subsection Common Type Attributes -The IA-64 back end supports the following variable attribute: +The following type attributes are supported on most targets. @table @code -@item model (@var{model-name}) -@cindex @code{model} variable attribute, IA-64 +@cindex @code{aligned} type attribute +@item aligned (@var{alignment}) +This attribute specifies a minimum alignment (in bytes) for variables +of the specified type. For example, the declarations: -On IA-64, use this attribute to set the addressability of an object. -At present, the only supported identifier for @var{model-name} is -@code{small}, indicating addressability via ``small'' (22-bit) -addresses (so that their addresses can be loaded with the @code{addl} -instruction). Caveat: such addressing is by definition not position -independent and hence this attribute must not be used for objects -defined by shared libraries. +@smallexample +struct S @{ short f[3]; @} __attribute__ ((aligned (8))); +typedef int more_aligned_int __attribute__ ((aligned (8))); +@end smallexample -@end table +@noindent +force the compiler to ensure (as far as it can) that each variable whose +type is @code{struct S} or @code{more_aligned_int} is allocated and +aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all +variables of type @code{struct S} aligned to 8-byte boundaries allows +the compiler to use the @code{ldd} and @code{std} (doubleword load and +store) instructions when copying one variable of type @code{struct S} to +another, thus improving run-time efficiency. -@node M32R/D Variable Attributes -@subsection M32R/D Variable Attributes +Note that the alignment of any given @code{struct} or @code{union} type +is required by the ISO C standard to be at least a perfect multiple of +the lowest common multiple of the alignments of all of the members of +the @code{struct} or @code{union} in question. This means that you @emph{can} +effectively adjust the alignment of a @code{struct} or @code{union} +type by attaching an @code{aligned} attribute to any one of the members +of such a type, but the notation illustrated in the example above is a +more obvious, intuitive, and readable way to request the compiler to +adjust the alignment of an entire @code{struct} or @code{union} type. -One attribute is currently defined for the M32R/D@. +As in the preceding example, you can explicitly specify the alignment +(in bytes) that you wish the compiler to use for a given @code{struct} +or @code{union} type. Alternatively, you can leave out the alignment factor +and just ask the compiler to align a type to the maximum +useful alignment for the target machine you are compiling for. For +example, you could write: -@table @code -@item model (@var{model-name}) -@cindex @code{model-name} variable attribute, M32R/D -@cindex variable addressability on the M32R/D -Use this attribute on the M32R/D to set the addressability of an object. -The identifier @var{model-name} is one of @code{small}, @code{medium}, -or @code{large}, representing each of the code models. +@smallexample +struct S @{ short f[3]; @} __attribute__ ((aligned)); +@end smallexample -Small model objects live in the lower 16MB of memory (so that their -addresses can be loaded with the @code{ld24} instruction). +Whenever you leave out the alignment factor in an @code{aligned} +attribute specification, the compiler automatically sets the alignment +for the type to the largest alignment that is ever used for any data +type on the target machine you are compiling for. Doing this can often +make copy operations more efficient, because the compiler can use +whatever instructions copy the biggest chunks of memory when performing +copies to or from the variables that have types that you have aligned +this way. -Medium and large model objects may live anywhere in the 32-bit address space -(the compiler generates @code{seth/add3} instructions to load their -addresses). -@end table +In the example above, if the size of each @code{short} is 2 bytes, then +the size of the entire @code{struct S} type is 6 bytes. The smallest +power of two that is greater than or equal to that is 8, so the +compiler sets the alignment for the entire @code{struct S} type to 8 +bytes. -@node MeP Variable Attributes -@subsection MeP Variable Attributes +Note that although you can ask the compiler to select a time-efficient +alignment for a given type and then declare only individual stand-alone +objects of that type, the compiler's ability to select a time-efficient +alignment is primarily useful only when you plan to create arrays of +variables having the relevant (efficiently aligned) type. If you +declare or use arrays of variables of an efficiently-aligned type, then +it is likely that your program also does pointer arithmetic (or +subscripting, which amounts to the same thing) on pointers to the +relevant type, and the code that the compiler generates for these +pointer arithmetic operations is often more efficient for +efficiently-aligned types than for other types. -The MeP target has a number of addressing modes and busses. The -@code{near} space spans the standard memory space's first 16 megabytes -(24 bits). The @code{far} space spans the entire 32-bit memory space. -The @code{based} space is a 128-byte region in the memory space that -is addressed relative to the @code{$tp} register. The @code{tiny} -space is a 65536-byte region relative to the @code{$gp} register. In -addition to these memory regions, the MeP target has a separate 16-bit -control bus which is specified with @code{cb} attributes. +The @code{aligned} attribute can only increase the alignment; but you +can decrease it by specifying @code{packed} as well. See below. -@table @code +Note that the effectiveness of @code{aligned} attributes may be limited +by inherent limitations in your linker. On many systems, the linker is +only able to arrange for variables to be aligned up to a certain maximum +alignment. (For some linkers, the maximum supported alignment may +be very very small.) If your linker is only able to align variables +up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} +in an @code{__attribute__} still only provides you with 8-byte +alignment. See your linker documentation for further information. -@item based -@cindex @code{based} variable attribute, MeP -Any variable with the @code{based} attribute is assigned to the -@code{.based} section, and is accessed with relative to the -@code{$tp} register. +@opindex fshort-enums +Specifying this attribute for @code{struct} and @code{union} types is +equivalent to specifying the @code{packed} attribute on each of the +structure or union members. Specifying the @option{-fshort-enums} +flag on the line is equivalent to specifying the @code{packed} +attribute on all @code{enum} definitions. -@item tiny -@cindex @code{tiny} variable attribute, MeP -Likewise, the @code{tiny} attribute assigned variables to the -@code{.tiny} section, relative to the @code{$gp} register. +In the following example @code{struct my_packed_struct}'s members are +packed closely together, but the internal layout of its @code{s} member +is not packed---to do that, @code{struct my_unpacked_struct} needs to +be packed too. -@item near -@cindex @code{near} variable attribute, MeP -Variables with the @code{near} attribute are assumed to have addresses -that fit in a 24-bit addressing mode. This is the default for large -variables (@code{-mtiny=4} is the default) but this attribute can -override @code{-mtiny=} for small variables, or override @code{-ml}. +@smallexample +struct my_unpacked_struct + @{ + char c; + int i; + @}; -@item far -@cindex @code{far} variable attribute, MeP -Variables with the @code{far} attribute are addressed using a full -32-bit address. Since this covers the entire memory space, this -allows modules to make no assumptions about where variables might be -stored. +struct __attribute__ ((__packed__)) my_packed_struct + @{ + char c; + int i; + struct my_unpacked_struct s; + @}; +@end smallexample -@item io -@cindex @code{io} variable attribute, MeP -@itemx io (@var{addr}) -Variables with the @code{io} attribute are used to address -memory-mapped peripherals. If an address is specified, the variable -is assigned that address, else it is not assigned an address (it is -assumed some other module assigns an address). Example: +You may only specify this attribute on the definition of an @code{enum}, +@code{struct} or @code{union}, not on a @code{typedef} that does not +also define the enumerated type, structure or union. + +@item bnd_variable_size +@cindex @code{bnd_variable_size} type attribute +@cindex Pointer Bounds Checker attributes +When applied to a structure field, this attribute tells Pointer +Bounds Checker that the size of this field should not be computed +using static type information. It may be used to mark variably-sized +static array fields placed at the end of a structure. @smallexample -int timer_count __attribute__((io(0x123))); +struct S +@{ + int size; + char data[1]; +@} +S *p = (S *)malloc (sizeof(S) + 100); +p->data[10] = 0; //Bounds violation @end smallexample -@item cb -@itemx cb (@var{addr}) -@cindex @code{cb} variable attribute, MeP -Variables with the @code{cb} attribute are used to access the control -bus, using special instructions. @code{addr} indicates the control bus -address. Example: +@noindent +By using an attribute for the field we may avoid unwanted bound +violation checks: @smallexample -int cpu_clock __attribute__((cb(0x123))); +struct S +@{ + int size; + char data[1] __attribute__((bnd_variable_size)); +@} +S *p = (S *)malloc (sizeof(S) + 100); +p->data[10] = 0; //OK @end smallexample -@end table - -@node Microsoft Windows Variable Attributes -@subsection Microsoft Windows Variable Attributes +@item deprecated +@itemx deprecated (@var{msg}) +@cindex @code{deprecated} type attribute +The @code{deprecated} attribute results in a warning if the type +is used anywhere in the source file. This is useful when identifying +types that are expected to be removed in a future version of a program. +If possible, the warning also includes the location of the declaration +of the deprecated type, to enable users to easily find further +information about why the type is deprecated, or what they should do +instead. Note that the warnings only occur for uses and then only +if the type is being applied to an identifier that itself is not being +declared as deprecated. -You can use these attributes on Microsoft Windows targets. -@ref{x86 Variable Attributes} for additional Windows compatibility -attributes available on all x86 targets. +@smallexample +typedef int T1 __attribute__ ((deprecated)); +T1 x; +typedef T1 T2; +T2 y; +typedef T1 T3 __attribute__ ((deprecated)); +T3 z __attribute__ ((deprecated)); +@end smallexample -@table @code -@item dllimport -@itemx dllexport -@cindex @code{dllimport} variable attribute -@cindex @code{dllexport} variable attribute -The @code{dllimport} and @code{dllexport} attributes are described in -@ref{Microsoft Windows Function Attributes}. +@noindent +results in a warning on line 2 and 3 but not lines 4, 5, or 6. No +warning is issued for line 4 because T2 is not explicitly +deprecated. Line 5 has no warning because T3 is explicitly +deprecated. Similarly for line 6. The optional @var{msg} +argument, which must be a string, is printed in the warning if +present. -@item selectany -@cindex @code{selectany} variable attribute -The @code{selectany} attribute causes an initialized global variable to -have link-once semantics. When multiple definitions of the variable are -encountered by the linker, the first is selected and the remainder are -discarded. Following usage by the Microsoft compiler, the linker is told -@emph{not} to warn about size or content differences of the multiple -definitions. +The @code{deprecated} attribute can also be used for functions and +variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) -Although the primary usage of this attribute is for POD types, the -attribute can also be applied to global C++ objects that are initialized -by a constructor. In this case, the static initialization and destruction -code for the object is emitted in each translation defining the object, -but the calls to the constructor and destructor are protected by a -link-once guard variable. +@item designated_init +@cindex @code{designated_init} type attribute +This attribute may only be applied to structure types. It indicates +that any initialization of an object of this type must use designated +initializers rather than positional initializers. The intent of this +attribute is to allow the programmer to indicate that a structure's +layout may change, and that therefore relying on positional +initialization will result in future breakage. -The @code{selectany} attribute is only available on Microsoft Windows -targets. You can use @code{__declspec (selectany)} as a synonym for -@code{__attribute__ ((selectany))} for compatibility with other -compilers. +GCC emits warnings based on this attribute by default; use +@option{-Wno-designated-init} to suppress them. -@item shared -@cindex @code{shared} variable attribute -On Microsoft Windows, in addition to putting variable definitions in a named -section, the section can also be shared among all running copies of an -executable or DLL@. For example, this small program defines shared data -by putting it in a named section @code{shared} and marking the section -shareable: +@item may_alias +@cindex @code{may_alias} type attribute +Accesses through pointers to types with this attribute are not subject +to type-based alias analysis, but are instead assumed to be able to alias +any other type of objects. +In the context of section 6.5 paragraph 7 of the C99 standard, +an lvalue expression +dereferencing such a pointer is treated like having a character type. +See @option{-fstrict-aliasing} for more information on aliasing issues. +This extension exists to support some vector APIs, in which pointers to +one vector type are permitted to alias pointers to a different vector type. + +Note that an object of a type with this attribute does not have any +special semantics. + +Example of use: @smallexample -int foo __attribute__((section ("shared"), shared)) = 0; +typedef short __attribute__((__may_alias__)) short_a; int -main() +main (void) @{ - /* @r{Read and write foo. All running - copies see the same value.} */ - return 0; + int a = 0x12345678; + short_a *b = (short_a *) &a; + + b[1] = 0; + + if (a == 0x12345678) + abort(); + + exit(0); @} @end smallexample @noindent -You may only use the @code{shared} attribute along with @code{section} -attribute with a fully-initialized global definition because of the way -linkers work. See @code{section} attribute for more information. - -The @code{shared} attribute is only available on Microsoft Windows@. - -@end table +If you replaced @code{short_a} with @code{short} in the variable +declaration, the above program would abort when compiled with +@option{-fstrict-aliasing}, which is on by default at @option{-O2} or +above. -@node PowerPC Variable Attributes -@subsection PowerPC Variable Attributes +@item packed +@cindex @code{packed} type attribute +This attribute, attached to @code{struct} or @code{union} type +definition, specifies that each member (other than zero-width bit-fields) +of the structure or union is placed to minimize the memory required. When +attached to an @code{enum} definition, it indicates that the smallest +integral type should be used. -Three attributes currently are defined for PowerPC configurations: -@code{altivec}, @code{ms_struct} and @code{gcc_struct}. +@item transparent_union +@cindex @code{transparent_union} type attribute -@cindex @code{ms_struct} variable attribute, PowerPC -@cindex @code{gcc_struct} variable attribute, PowerPC -For full documentation of the struct attributes please see the -documentation in @ref{x86 Variable Attributes}. +This attribute, attached to a @code{union} type definition, indicates +that any function parameter having that union type causes calls to that +function to be treated in a special way. -@cindex @code{altivec} variable attribute, PowerPC -For documentation of @code{altivec} attribute please see the -documentation in @ref{PowerPC Type Attributes}. +First, the argument corresponding to a transparent union type can be of +any type in the union; no cast is required. Also, if the union contains +a pointer type, the corresponding argument can be a null pointer +constant or a void pointer expression; and if the union contains a void +pointer type, the corresponding argument can be any pointer expression. +If the union member type is a pointer, qualifiers like @code{const} on +the referenced type must be respected, just as with normal pointer +conversions. -@node SPU Variable Attributes -@subsection SPU Variable Attributes +Second, the argument is passed to the function using the calling +conventions of the first member of the transparent union, not the calling +conventions of the union itself. All members of the union must have the +same machine representation; this is necessary for this argument passing +to work properly. -@cindex @code{spu_vector} variable attribute, SPU -The SPU supports the @code{spu_vector} attribute for variables. For -documentation of this attribute please see the documentation in -@ref{SPU Type Attributes}. +Transparent unions are designed for library functions that have multiple +interfaces for compatibility reasons. For example, suppose the +@code{wait} function must accept either a value of type @code{int *} to +comply with POSIX, or a value of type @code{union wait *} to comply with +the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, +@code{wait} would accept both kinds of arguments, but it would also +accept any other pointer type and this would make argument type checking +less useful. Instead, @code{} might define the interface +as follows: -@node x86 Variable Attributes -@subsection x86 Variable Attributes +@smallexample +typedef union __attribute__ ((__transparent_union__)) + @{ + int *__ip; + union wait *__up; + @} wait_status_ptr_t; -Two attributes are currently defined for x86 configurations: -@code{ms_struct} and @code{gcc_struct}. +pid_t wait (wait_status_ptr_t); +@end smallexample -@table @code -@item ms_struct -@itemx gcc_struct -@cindex @code{ms_struct} variable attribute, x86 -@cindex @code{gcc_struct} variable attribute, x86 +@noindent +This interface allows either @code{int *} or @code{union wait *} +arguments to be passed, using the @code{int *} calling convention. +The program can call @code{wait} with arguments of either type: -If @code{packed} is used on a structure, or if bit-fields are used, -it may be that the Microsoft ABI lays out the structure differently -than the way GCC normally does. Particularly when moving packed -data between functions compiled with GCC and the native Microsoft compiler -(either via function call or as data in a file), it may be necessary to access -either format. +@smallexample +int w1 () @{ int w; return wait (&w); @} +int w2 () @{ union wait w; return wait (&w); @} +@end smallexample -Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows x86 -compilers to match the native Microsoft compiler. +@noindent +With this interface, @code{wait}'s implementation might look like this: -The Microsoft structure layout algorithm is fairly simple with the exception -of the bit-field packing. -The padding and alignment of members of structures and whether a bit-field -can straddle a storage-unit boundary are determine by these rules: +@smallexample +pid_t wait (wait_status_ptr_t p) +@{ + return waitpid (-1, p.__ip, 0); +@} +@end smallexample -@enumerate -@item Structure members are stored sequentially in the order in which they are -declared: the first member has the lowest memory address and the last member -the highest. +@item unused +@cindex @code{unused} type attribute +When attached to a type (including a @code{union} or a @code{struct}), +this attribute means that variables of that type are meant to appear +possibly unused. GCC does not produce a warning for any variables of +that type, even if the variable appears to do nothing. This is often +the case with lock or thread classes, which are usually defined and then +not referenced, but contain constructors and destructors that have +nontrivial bookkeeping functions. -@item Every data object has an alignment requirement. The alignment requirement -for all data except structures, unions, and arrays is either the size of the -object or the current packing size (specified with either the -@code{aligned} attribute or the @code{pack} pragma), -whichever is less. For structures, unions, and arrays, -the alignment requirement is the largest alignment requirement of its members. -Every object is allocated an offset so that: +@item visibility +@cindex @code{visibility} type attribute +In C++, attribute visibility (@pxref{Function Attributes}) can also be +applied to class, struct, union and enum types. Unlike other type +attributes, the attribute must appear between the initial keyword and +the name of the type; it cannot appear after the body of the type. -@smallexample -offset % alignment_requirement == 0 -@end smallexample +Note that the type visibility is applied to vague linkage entities +associated with the class (vtable, typeinfo node, etc.). In +particular, if a class is thrown as an exception in one shared object +and caught in another, the class must have default visibility. +Otherwise the two shared objects are unable to use the same +typeinfo node and exception handling will break. -@item Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation -unit if the integral types are the same size and if the next bit-field fits -into the current allocation unit without crossing the boundary imposed by the -common alignment requirements of the bit-fields. -@end enumerate +@end table -MSVC interprets zero-length bit-fields in the following ways: +To specify multiple attributes, separate them by commas within the +double parentheses: for example, @samp{__attribute__ ((aligned (16), +packed))}. -@enumerate -@item If a zero-length bit-field is inserted between two bit-fields that -are normally coalesced, the bit-fields are not coalesced. +@node ARM Type Attributes +@subsection ARM Type Attributes -For example: +@cindex @code{notshared} type attribute, ARM +On those ARM targets that support @code{dllimport} (such as Symbian +OS), you can use the @code{notshared} attribute to indicate that the +virtual table and other similar data for a class should not be +exported from a DLL@. For example: @smallexample -struct - @{ - unsigned long bf_1 : 12; - unsigned long : 0; - unsigned long bf_2 : 12; - @} t1; -@end smallexample +class __declspec(notshared) C @{ +public: + __declspec(dllimport) C(); + virtual void f(); +@} -@noindent -The size of @code{t1} is 8 bytes with the zero-length bit-field. If the -zero-length bit-field were removed, @code{t1}'s size would be 4 bytes. - -@item If a zero-length bit-field is inserted after a bit-field, @code{foo}, and the -alignment of the zero-length bit-field is greater than the member that follows it, -@code{bar}, @code{bar} is aligned as the type of the zero-length bit-field. - -For example: - -@smallexample -struct - @{ - char foo : 4; - short : 0; - char bar; - @} t2; - -struct - @{ - char foo : 4; - short : 0; - double bar; - @} t3; +__declspec(dllexport) +C::C() @{@} @end smallexample @noindent -For @code{t2}, @code{bar} is placed at offset 2, rather than offset 1. -Accordingly, the size of @code{t2} is 4. For @code{t3}, the zero-length -bit-field does not affect the alignment of @code{bar} or, as a result, the size -of the structure. +In this code, @code{C::C} is exported from the current DLL, but the +virtual table for @code{C} is not exported. (You can use +@code{__attribute__} instead of @code{__declspec} if you prefer, but +most Symbian OS code uses @code{__declspec}.) -Taking this into account, it is important to note the following: +@node MeP Type Attributes +@subsection MeP Type Attributes -@enumerate -@item If a zero-length bit-field follows a normal bit-field, the type of the -zero-length bit-field may affect the alignment of the structure as whole. For -example, @code{t2} has a size of 4 bytes, since the zero-length bit-field follows a -normal bit-field, and is of type short. +@cindex @code{based} type attribute, MeP +@cindex @code{tiny} type attribute, MeP +@cindex @code{near} type attribute, MeP +@cindex @code{far} type attribute, MeP +Many of the MeP variable attributes may be applied to types as well. +Specifically, the @code{based}, @code{tiny}, @code{near}, and +@code{far} attributes may be applied to either. The @code{io} and +@code{cb} attributes may not be applied to types. -@item Even if a zero-length bit-field is not followed by a normal bit-field, it may -still affect the alignment of the structure: +@node PowerPC Type Attributes +@subsection PowerPC Type Attributes -@smallexample -struct - @{ - char foo : 6; - long : 0; - @} t4; -@end smallexample +Three attributes currently are defined for PowerPC configurations: +@code{altivec}, @code{ms_struct} and @code{gcc_struct}. -@noindent -Here, @code{t4} takes up 4 bytes. -@end enumerate +@cindex @code{ms_struct} type attribute, PowerPC +@cindex @code{gcc_struct} type attribute, PowerPC +For full documentation of the @code{ms_struct} and @code{gcc_struct} +attributes please see the documentation in @ref{x86 Type Attributes}. -@item Zero-length bit-fields following non-bit-field members are ignored: +@cindex @code{altivec} type attribute, PowerPC +The @code{altivec} attribute allows one to declare AltiVec vector data +types supported by the AltiVec Programming Interface Manual. The +attribute requires an argument to specify one of three vector types: +@code{vector__}, @code{pixel__} (always followed by unsigned short), +and @code{bool__} (always followed by unsigned). @smallexample -struct - @{ - char foo; - long : 0; - char bar; - @} t5; +__attribute__((altivec(vector__))) +__attribute__((altivec(pixel__))) unsigned short +__attribute__((altivec(bool__))) unsigned @end smallexample -@noindent -Here, @code{t5} takes up 2 bytes. -@end enumerate -@end table +These attributes mainly are intended to support the @code{__vector}, +@code{__pixel}, and @code{__bool} AltiVec keywords. -@node Xstormy16 Variable Attributes -@subsection Xstormy16 Variable Attributes +@node SPU Type Attributes +@subsection SPU Type Attributes -One attribute is currently defined for xstormy16 configurations: -@code{below100}. +@cindex @code{spu_vector} type attribute, SPU +The SPU supports the @code{spu_vector} attribute for types. This attribute +allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU +Language Extensions Specification. It is intended to support the +@code{__vector} keyword. -@table @code -@item below100 -@cindex @code{below100} variable attribute, Xstormy16 +@node x86 Type Attributes +@subsection x86 Type Attributes -If a variable has the @code{below100} attribute (@code{BELOW100} is -allowed also), GCC places the variable in the first 0x100 bytes of -memory and use special opcodes to access it. Such variables are -placed in either the @code{.bss_below100} section or the -@code{.data_below100} section. +Two attributes are currently defined for x86 configurations: +@code{ms_struct} and @code{gcc_struct}. -@end table +@table @code -@node Type Attributes -@section Specifying Attributes of Types -@cindex attribute of types -@cindex type attributes +@item ms_struct +@itemx gcc_struct +@cindex @code{ms_struct} type attribute, x86 +@cindex @code{gcc_struct} type attribute, x86 -The keyword @code{__attribute__} allows you to specify special -attributes of types. Some type attributes apply only to @code{struct} -and @code{union} types, while others can apply to any type defined -via a @code{typedef} declaration. Other attributes are defined for -functions (@pxref{Function Attributes}), labels (@pxref{Label -Attributes}) and for variables (@pxref{Variable Attributes}). +If @code{packed} is used on a structure, or if bit-fields are used +it may be that the Microsoft ABI packs them differently +than GCC normally packs them. Particularly when moving packed +data between functions compiled with GCC and the native Microsoft compiler +(either via function call or as data in a file), it may be necessary to access +either format. -The @code{__attribute__} keyword is followed by an attribute specification -inside double parentheses. +Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows x86 +compilers to match the native Microsoft compiler. +@end table -You may specify type attributes in an enum, struct or union type -declaration or definition by placing them immediately after the -@code{struct}, @code{union} or @code{enum} keyword. A less preferred -syntax is to place them just past the closing curly brace of the -definition. +@node Label Attributes +@section Label Attributes +@cindex Label Attributes -You can also include type attributes in a @code{typedef} declaration. -@xref{Attribute Syntax}, for details of the exact syntax for using -attributes. +GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for +details of the exact syntax for using attributes. Other attributes are +available for functions (@pxref{Function Attributes}), variables +(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}). -@menu -* Common Type Attributes:: -* ARM Type Attributes:: -* MeP Type Attributes:: -* PowerPC Type Attributes:: -* SPU Type Attributes:: -* x86 Type Attributes:: -@end menu +This example uses the @code{cold} label attribute to indicate the +@code{ErrorHandling} branch is unlikely to be taken and that the +@code{ErrorHandling} label is unused: -@node Common Type Attributes -@subsection Common Type Attributes +@smallexample -The following type attributes are supported on most targets. + asm goto ("some asm" : : : : NoError); -@table @code -@cindex @code{aligned} type attribute -@item aligned (@var{alignment}) -This attribute specifies a minimum alignment (in bytes) for variables -of the specified type. For example, the declarations: +/* This branch (the fall-through from the asm) is less commonly used */ +ErrorHandling: + __attribute__((cold, unused)); /* Semi-colon is required here */ + printf("error\n"); + return 0; -@smallexample -struct S @{ short f[3]; @} __attribute__ ((aligned (8))); -typedef int more_aligned_int __attribute__ ((aligned (8))); +NoError: + printf("no error\n"); + return 1; @end smallexample -@noindent -force the compiler to ensure (as far as it can) that each variable whose -type is @code{struct S} or @code{more_aligned_int} is allocated and -aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all -variables of type @code{struct S} aligned to 8-byte boundaries allows -the compiler to use the @code{ldd} and @code{std} (doubleword load and -store) instructions when copying one variable of type @code{struct S} to -another, thus improving run-time efficiency. - -Note that the alignment of any given @code{struct} or @code{union} type -is required by the ISO C standard to be at least a perfect multiple of -the lowest common multiple of the alignments of all of the members of -the @code{struct} or @code{union} in question. This means that you @emph{can} -effectively adjust the alignment of a @code{struct} or @code{union} -type by attaching an @code{aligned} attribute to any one of the members -of such a type, but the notation illustrated in the example above is a -more obvious, intuitive, and readable way to request the compiler to -adjust the alignment of an entire @code{struct} or @code{union} type. +@table @code +@item unused +@cindex @code{unused} label attribute +This feature is intended for program-generated code that may contain +unused labels, but which is compiled with @option{-Wall}. It is +not normally appropriate to use in it human-written code, though it +could be useful in cases where the code that jumps to the label is +contained within an @code{#ifdef} conditional. -As in the preceding example, you can explicitly specify the alignment -(in bytes) that you wish the compiler to use for a given @code{struct} -or @code{union} type. Alternatively, you can leave out the alignment factor -and just ask the compiler to align a type to the maximum -useful alignment for the target machine you are compiling for. For -example, you could write: +@item hot +@cindex @code{hot} label attribute +The @code{hot} attribute on a label is used to inform the compiler that +the path following the label is more likely than paths that are not so +annotated. This attribute is used in cases where @code{__builtin_expect} +cannot be used, for instance with computed goto or @code{asm goto}. -@smallexample -struct S @{ short f[3]; @} __attribute__ ((aligned)); -@end smallexample +@item cold +@cindex @code{cold} label attribute +The @code{cold} attribute on labels is used to inform the compiler that +the path following the label is unlikely to be executed. This attribute +is used in cases where @code{__builtin_expect} cannot be used, for instance +with computed goto or @code{asm goto}. -Whenever you leave out the alignment factor in an @code{aligned} -attribute specification, the compiler automatically sets the alignment -for the type to the largest alignment that is ever used for any data -type on the target machine you are compiling for. Doing this can often -make copy operations more efficient, because the compiler can use -whatever instructions copy the biggest chunks of memory when performing -copies to or from the variables that have types that you have aligned -this way. +@end table -In the example above, if the size of each @code{short} is 2 bytes, then -the size of the entire @code{struct S} type is 6 bytes. The smallest -power of two that is greater than or equal to that is 8, so the -compiler sets the alignment for the entire @code{struct S} type to 8 -bytes. +@node Attribute Syntax +@section Attribute Syntax +@cindex attribute syntax -Note that although you can ask the compiler to select a time-efficient -alignment for a given type and then declare only individual stand-alone -objects of that type, the compiler's ability to select a time-efficient -alignment is primarily useful only when you plan to create arrays of -variables having the relevant (efficiently aligned) type. If you -declare or use arrays of variables of an efficiently-aligned type, then -it is likely that your program also does pointer arithmetic (or -subscripting, which amounts to the same thing) on pointers to the -relevant type, and the code that the compiler generates for these -pointer arithmetic operations is often more efficient for -efficiently-aligned types than for other types. - -The @code{aligned} attribute can only increase the alignment; but you -can decrease it by specifying @code{packed} as well. See below. - -Note that the effectiveness of @code{aligned} attributes may be limited -by inherent limitations in your linker. On many systems, the linker is -only able to arrange for variables to be aligned up to a certain maximum -alignment. (For some linkers, the maximum supported alignment may -be very very small.) If your linker is only able to align variables -up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} -in an @code{__attribute__} still only provides you with 8-byte -alignment. See your linker documentation for further information. - -@opindex fshort-enums -Specifying this attribute for @code{struct} and @code{union} types is -equivalent to specifying the @code{packed} attribute on each of the -structure or union members. Specifying the @option{-fshort-enums} -flag on the line is equivalent to specifying the @code{packed} -attribute on all @code{enum} definitions. - -In the following example @code{struct my_packed_struct}'s members are -packed closely together, but the internal layout of its @code{s} member -is not packed---to do that, @code{struct my_unpacked_struct} needs to -be packed too. - -@smallexample -struct my_unpacked_struct - @{ - char c; - int i; - @}; - -struct __attribute__ ((__packed__)) my_packed_struct - @{ - char c; - int i; - struct my_unpacked_struct s; - @}; -@end smallexample - -You may only specify this attribute on the definition of an @code{enum}, -@code{struct} or @code{union}, not on a @code{typedef} that does not -also define the enumerated type, structure or union. - -@item bnd_variable_size -@cindex @code{bnd_variable_size} type attribute -@cindex Pointer Bounds Checker attributes -When applied to a structure field, this attribute tells Pointer -Bounds Checker that the size of this field should not be computed -using static type information. It may be used to mark variably-sized -static array fields placed at the end of a structure. - -@smallexample -struct S -@{ - int size; - char data[1]; -@} -S *p = (S *)malloc (sizeof(S) + 100); -p->data[10] = 0; //Bounds violation -@end smallexample - -@noindent -By using an attribute for the field we may avoid unwanted bound -violation checks: - -@smallexample -struct S -@{ - int size; - char data[1] __attribute__((bnd_variable_size)); -@} -S *p = (S *)malloc (sizeof(S) + 100); -p->data[10] = 0; //OK -@end smallexample - -@item deprecated -@itemx deprecated (@var{msg}) -@cindex @code{deprecated} type attribute -The @code{deprecated} attribute results in a warning if the type -is used anywhere in the source file. This is useful when identifying -types that are expected to be removed in a future version of a program. -If possible, the warning also includes the location of the declaration -of the deprecated type, to enable users to easily find further -information about why the type is deprecated, or what they should do -instead. Note that the warnings only occur for uses and then only -if the type is being applied to an identifier that itself is not being -declared as deprecated. - -@smallexample -typedef int T1 __attribute__ ((deprecated)); -T1 x; -typedef T1 T2; -T2 y; -typedef T1 T3 __attribute__ ((deprecated)); -T3 z __attribute__ ((deprecated)); -@end smallexample +This section describes the syntax with which @code{__attribute__} may be +used, and the constructs to which attribute specifiers bind, for the C +language. Some details may vary for C++ and Objective-C@. Because of +infelicities in the grammar for attributes, some forms described here +may not be successfully parsed in all cases. -@noindent -results in a warning on line 2 and 3 but not lines 4, 5, or 6. No -warning is issued for line 4 because T2 is not explicitly -deprecated. Line 5 has no warning because T3 is explicitly -deprecated. Similarly for line 6. The optional @var{msg} -argument, which must be a string, is printed in the warning if -present. +There are some problems with the semantics of attributes in C++. For +example, there are no manglings for attributes, although they may affect +code generation, so problems may arise when attributed types are used in +conjunction with templates or overloading. Similarly, @code{typeid} +does not distinguish between types with different attributes. Support +for attributes in C++ may be restricted in future to attributes on +declarations only, but not on nested declarators. -The @code{deprecated} attribute can also be used for functions and -variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) +@xref{Function Attributes}, for details of the semantics of attributes +applying to functions. @xref{Variable Attributes}, for details of the +semantics of attributes applying to variables. @xref{Type Attributes}, +for details of the semantics of attributes applying to structure, union +and enumerated types. +@xref{Label Attributes}, for details of the semantics of attributes +applying to labels. -@item designated_init -@cindex @code{designated_init} type attribute -This attribute may only be applied to structure types. It indicates -that any initialization of an object of this type must use designated -initializers rather than positional initializers. The intent of this -attribute is to allow the programmer to indicate that a structure's -layout may change, and that therefore relying on positional -initialization will result in future breakage. +An @dfn{attribute specifier} is of the form +@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} +is a possibly empty comma-separated sequence of @dfn{attributes}, where +each attribute is one of the following: -GCC emits warnings based on this attribute by default; use -@option{-Wno-designated-init} to suppress them. +@itemize @bullet +@item +Empty. Empty attributes are ignored. -@item may_alias -@cindex @code{may_alias} type attribute -Accesses through pointers to types with this attribute are not subject -to type-based alias analysis, but are instead assumed to be able to alias -any other type of objects. -In the context of section 6.5 paragraph 7 of the C99 standard, -an lvalue expression -dereferencing such a pointer is treated like having a character type. -See @option{-fstrict-aliasing} for more information on aliasing issues. -This extension exists to support some vector APIs, in which pointers to -one vector type are permitted to alias pointers to a different vector type. +@item +An attribute name +(which may be an identifier such as @code{unused}, or a reserved +word such as @code{const}). -Note that an object of a type with this attribute does not have any -special semantics. +@item +An attribute name followed by a parenthesized list of +parameters for the attribute. +These parameters take one of the following forms: -Example of use: +@itemize @bullet +@item +An identifier. For example, @code{mode} attributes use this form. -@smallexample -typedef short __attribute__((__may_alias__)) short_a; +@item +An identifier followed by a comma and a non-empty comma-separated list +of expressions. For example, @code{format} attributes use this form. -int -main (void) -@{ - int a = 0x12345678; - short_a *b = (short_a *) &a; +@item +A possibly empty comma-separated list of expressions. For example, +@code{format_arg} attributes use this form with the list being a single +integer constant expression, and @code{alias} attributes use this form +with the list being a single string constant. +@end itemize +@end itemize - b[1] = 0; +An @dfn{attribute specifier list} is a sequence of one or more attribute +specifiers, not separated by any other tokens. - if (a == 0x12345678) - abort(); +You may optionally specify attribute names with @samp{__} +preceding and following the name. +This allows you to use them in header files without +being concerned about a possible macro of the same name. For example, +you may use the attribute name @code{__noreturn__} instead of @code{noreturn}. - exit(0); -@} -@end smallexample -@noindent -If you replaced @code{short_a} with @code{short} in the variable -declaration, the above program would abort when compiled with -@option{-fstrict-aliasing}, which is on by default at @option{-O2} or -above. +@subsubheading Label Attributes -@item packed -@cindex @code{packed} type attribute -This attribute, attached to @code{struct} or @code{union} type -definition, specifies that each member (other than zero-width bit-fields) -of the structure or union is placed to minimize the memory required. When -attached to an @code{enum} definition, it indicates that the smallest -integral type should be used. +In GNU C, an attribute specifier list may appear after the colon following a +label, other than a @code{case} or @code{default} label. GNU C++ only permits +attributes on labels if the attribute specifier is immediately +followed by a semicolon (i.e., the label applies to an empty +statement). If the semicolon is missing, C++ label attributes are +ambiguous, as it is permissible for a declaration, which could begin +with an attribute list, to be labelled in C++. Declarations cannot be +labelled in C90 or C99, so the ambiguity does not arise there. -@item transparent_union -@cindex @code{transparent_union} type attribute +@subsubheading Type Attributes -This attribute, attached to a @code{union} type definition, indicates -that any function parameter having that union type causes calls to that -function to be treated in a special way. +An attribute specifier list may appear as part of a @code{struct}, +@code{union} or @code{enum} specifier. It may go either immediately +after the @code{struct}, @code{union} or @code{enum} keyword, or after +the closing brace. The former syntax is preferred. +Where attribute specifiers follow the closing brace, they are considered +to relate to the structure, union or enumerated type defined, not to any +enclosing declaration the type specifier appears in, and the type +defined is not complete until after the attribute specifiers. +@c Otherwise, there would be the following problems: a shift/reduce +@c conflict between attributes binding the struct/union/enum and +@c binding to the list of specifiers/qualifiers; and "aligned" +@c attributes could use sizeof for the structure, but the size could be +@c changed later by "packed" attributes. -First, the argument corresponding to a transparent union type can be of -any type in the union; no cast is required. Also, if the union contains -a pointer type, the corresponding argument can be a null pointer -constant or a void pointer expression; and if the union contains a void -pointer type, the corresponding argument can be any pointer expression. -If the union member type is a pointer, qualifiers like @code{const} on -the referenced type must be respected, just as with normal pointer -conversions. -Second, the argument is passed to the function using the calling -conventions of the first member of the transparent union, not the calling -conventions of the union itself. All members of the union must have the -same machine representation; this is necessary for this argument passing -to work properly. +@subsubheading All other attributes -Transparent unions are designed for library functions that have multiple -interfaces for compatibility reasons. For example, suppose the -@code{wait} function must accept either a value of type @code{int *} to -comply with POSIX, or a value of type @code{union wait *} to comply with -the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, -@code{wait} would accept both kinds of arguments, but it would also -accept any other pointer type and this would make argument type checking -less useful. Instead, @code{} might define the interface -as follows: +Otherwise, an attribute specifier appears as part of a declaration, +counting declarations of unnamed parameters and type names, and relates +to that declaration (which may be nested in another declaration, for +example in the case of a parameter declaration), or to a particular declarator +within a declaration. Where an +attribute specifier is applied to a parameter declared as a function or +an array, it should apply to the function or array rather than the +pointer to which the parameter is implicitly converted, but this is not +yet correctly implemented. -@smallexample -typedef union __attribute__ ((__transparent_union__)) - @{ - int *__ip; - union wait *__up; - @} wait_status_ptr_t; +Any list of specifiers and qualifiers at the start of a declaration may +contain attribute specifiers, whether or not such a list may in that +context contain storage class specifiers. (Some attributes, however, +are essentially in the nature of storage class specifiers, and only make +sense where storage class specifiers may be used; for example, +@code{section}.) There is one necessary limitation to this syntax: the +first old-style parameter declaration in a function definition cannot +begin with an attribute specifier, because such an attribute applies to +the function instead by syntax described below (which, however, is not +yet implemented in this case). In some other cases, attribute +specifiers are permitted by this grammar but not yet supported by the +compiler. All attribute specifiers in this place relate to the +declaration as a whole. In the obsolescent usage where a type of +@code{int} is implied by the absence of type specifiers, such a list of +specifiers and qualifiers may be an attribute specifier list with no +other specifiers or qualifiers. -pid_t wait (wait_status_ptr_t); -@end smallexample +At present, the first parameter in a function prototype must have some +type specifier that is not an attribute specifier; this resolves an +ambiguity in the interpretation of @code{void f(int +(__attribute__((foo)) x))}, but is subject to change. At present, if +the parentheses of a function declarator contain only attributes then +those attributes are ignored, rather than yielding an error or warning +or implying a single parameter of type int, but this is subject to +change. -@noindent -This interface allows either @code{int *} or @code{union wait *} -arguments to be passed, using the @code{int *} calling convention. -The program can call @code{wait} with arguments of either type: +An attribute specifier list may appear immediately before a declarator +(other than the first) in a comma-separated list of declarators in a +declaration of more than one identifier using a single list of +specifiers and qualifiers. Such attribute specifiers apply +only to the identifier before whose declarator they appear. For +example, in @smallexample -int w1 () @{ int w; return wait (&w); @} -int w2 () @{ union wait w; return wait (&w); @} +__attribute__((noreturn)) void d0 (void), + __attribute__((format(printf, 1, 2))) d1 (const char *, ...), + d2 (void); @end smallexample @noindent -With this interface, @code{wait}'s implementation might look like this: +the @code{noreturn} attribute applies to all the functions +declared; the @code{format} attribute only applies to @code{d1}. -@smallexample -pid_t wait (wait_status_ptr_t p) -@{ - return waitpid (-1, p.__ip, 0); -@} -@end smallexample +An attribute specifier list may appear immediately before the comma, +@code{=} or semicolon terminating the declaration of an identifier other +than a function definition. Such attribute specifiers apply +to the declared object or function. Where an +assembler name for an object or function is specified (@pxref{Asm +Labels}), the attribute must follow the @code{asm} +specification. -@item unused -@cindex @code{unused} type attribute -When attached to a type (including a @code{union} or a @code{struct}), -this attribute means that variables of that type are meant to appear -possibly unused. GCC does not produce a warning for any variables of -that type, even if the variable appears to do nothing. This is often -the case with lock or thread classes, which are usually defined and then -not referenced, but contain constructors and destructors that have -nontrivial bookkeeping functions. +An attribute specifier list may, in future, be permitted to appear after +the declarator in a function definition (before any old-style parameter +declarations or the function body). -@item visibility -@cindex @code{visibility} type attribute -In C++, attribute visibility (@pxref{Function Attributes}) can also be -applied to class, struct, union and enum types. Unlike other type -attributes, the attribute must appear between the initial keyword and -the name of the type; it cannot appear after the body of the type. +Attribute specifiers may be mixed with type qualifiers appearing inside +the @code{[]} of a parameter array declarator, in the C99 construct by +which such qualifiers are applied to the pointer to which the array is +implicitly converted. Such attribute specifiers apply to the pointer, +not to the array, but at present this is not implemented and they are +ignored. -Note that the type visibility is applied to vague linkage entities -associated with the class (vtable, typeinfo node, etc.). In -particular, if a class is thrown as an exception in one shared object -and caught in another, the class must have default visibility. -Otherwise the two shared objects are unable to use the same -typeinfo node and exception handling will break. +An attribute specifier list may appear at the start of a nested +declarator. At present, there are some limitations in this usage: the +attributes correctly apply to the declarator, but for most individual +attributes the semantics this implies are not implemented. +When attribute specifiers follow the @code{*} of a pointer +declarator, they may be mixed with any type qualifiers present. +The following describes the formal semantics of this syntax. It makes the +most sense if you are familiar with the formal specification of +declarators in the ISO C standard. -@end table +Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T +D1}, where @code{T} contains declaration specifiers that specify a type +@var{Type} (such as @code{int}) and @code{D1} is a declarator that +contains an identifier @var{ident}. The type specified for @var{ident} +for derived declarators whose type does not include an attribute +specifier is as in the ISO C standard. -To specify multiple attributes, separate them by commas within the -double parentheses: for example, @samp{__attribute__ ((aligned (16), -packed))}. +If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, +and the declaration @code{T D} specifies the type +``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then +@code{T D1} specifies the type ``@var{derived-declarator-type-list} +@var{attribute-specifier-list} @var{Type}'' for @var{ident}. -@node ARM Type Attributes -@subsection ARM Type Attributes +If @code{D1} has the form @code{* +@var{type-qualifier-and-attribute-specifier-list} D}, and the +declaration @code{T D} specifies the type +``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then +@code{T D1} specifies the type ``@var{derived-declarator-type-list} +@var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for +@var{ident}. -@cindex @code{notshared} type attribute, ARM -On those ARM targets that support @code{dllimport} (such as Symbian -OS), you can use the @code{notshared} attribute to indicate that the -virtual table and other similar data for a class should not be -exported from a DLL@. For example: +For example, @smallexample -class __declspec(notshared) C @{ -public: - __declspec(dllimport) C(); - virtual void f(); -@} - -__declspec(dllexport) -C::C() @{@} +void (__attribute__((noreturn)) ****f) (void); @end smallexample @noindent -In this code, @code{C::C} is exported from the current DLL, but the -virtual table for @code{C} is not exported. (You can use -@code{__attribute__} instead of @code{__declspec} if you prefer, but -most Symbian OS code uses @code{__declspec}.) - -@node MeP Type Attributes -@subsection MeP Type Attributes +specifies the type ``pointer to pointer to pointer to pointer to +non-returning function returning @code{void}''. As another example, -@cindex @code{based} type attribute, MeP -@cindex @code{tiny} type attribute, MeP -@cindex @code{near} type attribute, MeP -@cindex @code{far} type attribute, MeP -Many of the MeP variable attributes may be applied to types as well. -Specifically, the @code{based}, @code{tiny}, @code{near}, and -@code{far} attributes may be applied to either. The @code{io} and -@code{cb} attributes may not be applied to types. +@smallexample +char *__attribute__((aligned(8))) *f; +@end smallexample -@node PowerPC Type Attributes -@subsection PowerPC Type Attributes +@noindent +specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. +Note again that this does not work with most attributes; for example, +the usage of @samp{aligned} and @samp{noreturn} attributes given above +is not yet supported. -Three attributes currently are defined for PowerPC configurations: -@code{altivec}, @code{ms_struct} and @code{gcc_struct}. +For compatibility with existing code written for compiler versions that +did not implement attributes on nested declarators, some laxity is +allowed in the placing of attributes. If an attribute that only applies +to types is applied to a declaration, it is treated as applying to +the type of that declaration. If an attribute that only applies to +declarations is applied to the type of a declaration, it is treated +as applying to that declaration; and, for compatibility with code +placing the attributes immediately before the identifier declared, such +an attribute applied to a function return type is treated as +applying to the function type, and such an attribute applied to an array +element type is treated as applying to the array type. If an +attribute that only applies to function types is applied to a +pointer-to-function type, it is treated as applying to the pointer +target type; if such an attribute is applied to a function return type +that is not a pointer-to-function type, it is treated as applying +to the function type. -@cindex @code{ms_struct} type attribute, PowerPC -@cindex @code{gcc_struct} type attribute, PowerPC -For full documentation of the @code{ms_struct} and @code{gcc_struct} -attributes please see the documentation in @ref{x86 Type Attributes}. +@node Function Prototypes +@section Prototypes and Old-Style Function Definitions +@cindex function prototype declarations +@cindex old-style function definitions +@cindex promotion of formal parameters -@cindex @code{altivec} type attribute, PowerPC -The @code{altivec} attribute allows one to declare AltiVec vector data -types supported by the AltiVec Programming Interface Manual. The -attribute requires an argument to specify one of three vector types: -@code{vector__}, @code{pixel__} (always followed by unsigned short), -and @code{bool__} (always followed by unsigned). +GNU C extends ISO C to allow a function prototype to override a later +old-style non-prototype definition. Consider the following example: @smallexample -__attribute__((altivec(vector__))) -__attribute__((altivec(pixel__))) unsigned short -__attribute__((altivec(bool__))) unsigned +/* @r{Use prototypes unless the compiler is old-fashioned.} */ +#ifdef __STDC__ +#define P(x) x +#else +#define P(x) () +#endif + +/* @r{Prototype function declaration.} */ +int isroot P((uid_t)); + +/* @r{Old-style function definition.} */ +int +isroot (x) /* @r{??? lossage here ???} */ + uid_t x; +@{ + return x == 0; +@} @end smallexample -These attributes mainly are intended to support the @code{__vector}, -@code{__pixel}, and @code{__bool} AltiVec keywords. +Suppose the type @code{uid_t} happens to be @code{short}. ISO C does +not allow this example, because subword arguments in old-style +non-prototype definitions are promoted. Therefore in this example the +function definition's argument is really an @code{int}, which does not +match the prototype argument type of @code{short}. -@node SPU Type Attributes -@subsection SPU Type Attributes +This restriction of ISO C makes it hard to write code that is portable +to traditional C compilers, because the programmer does not know +whether the @code{uid_t} type is @code{short}, @code{int}, or +@code{long}. Therefore, in cases like these GNU C allows a prototype +to override a later old-style definition. More precisely, in GNU C, a +function prototype argument type overrides the argument type specified +by a later old-style definition if the former type is the same as the +latter type before promotion. Thus in GNU C the above example is +equivalent to the following: -@cindex @code{spu_vector} type attribute, SPU -The SPU supports the @code{spu_vector} attribute for types. This attribute -allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU -Language Extensions Specification. It is intended to support the -@code{__vector} keyword. +@smallexample +int isroot (uid_t); -@node x86 Type Attributes -@subsection x86 Type Attributes +int +isroot (uid_t x) +@{ + return x == 0; +@} +@end smallexample -Two attributes are currently defined for x86 configurations: -@code{ms_struct} and @code{gcc_struct}. +@noindent +GNU C++ does not support old-style function definitions, so this +extension is irrelevant. -@table @code +@node C++ Comments +@section C++ Style Comments +@cindex @code{//} +@cindex C++ comments +@cindex comments, C++ style -@item ms_struct -@itemx gcc_struct -@cindex @code{ms_struct} type attribute, x86 -@cindex @code{gcc_struct} type attribute, x86 +In GNU C, you may use C++ style comments, which start with @samp{//} and +continue until the end of the line. Many other C implementations allow +such comments, and they are included in the 1999 C standard. However, +C++ style comments are not recognized if you specify an @option{-std} +option specifying a version of ISO C before C99, or @option{-ansi} +(equivalent to @option{-std=c90}). -If @code{packed} is used on a structure, or if bit-fields are used -it may be that the Microsoft ABI packs them differently -than GCC normally packs them. Particularly when moving packed -data between functions compiled with GCC and the native Microsoft compiler -(either via function call or as data in a file), it may be necessary to access -either format. +@node Dollar Signs +@section Dollar Signs in Identifier Names +@cindex $ +@cindex dollar signs in identifier names +@cindex identifier names, dollar signs in -Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows x86 -compilers to match the native Microsoft compiler. -@end table +In GNU C, you may normally use dollar signs in identifier names. +This is because many traditional C implementations allow such identifiers. +However, dollar signs in identifiers are not supported on a few target +machines, typically because the target assembler does not allow them. + +@node Character Escapes +@section The Character @key{ESC} in Constants + +You can use the sequence @samp{\e} in a string or character constant to +stand for the ASCII character @key{ESC}. @node Alignment @section Inquiring on Alignment of Types or Variables