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 <avr/pgmspace.h>
+
+/* 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 <avr/pgmspace.h>
+@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{<sys/wait.h>} 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{<sys/wait.h>} 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
projects / gcc.git / commitdiff