gcc: Attribute Syntax

1 
1 6.37 Attribute Syntax
1 =====================
1 
1 This section describes the syntax with which '__attribute__' may be
1 used, and the constructs to which attribute specifiers bind, for the C
1 language.  Some details may vary for C++ and Objective-C.  Because of
1 infelicities in the grammar for attributes, some forms described here
1 may not be successfully parsed in all cases.
1 
1  There are some problems with the semantics of attributes in C++.  For
1 example, there are no manglings for attributes, although they may affect
1 code generation, so problems may arise when attributed types are used in
1 conjunction with templates or overloading.  Similarly, 'typeid' does not
1 distinguish between types with different attributes.  Support for
1 attributes in C++ may be restricted in future to attributes on
1 declarations only, but not on nested declarators.
1 
1  ⇒Function Attributes, for details of the semantics of attributes
1 applying to functions.  ⇒Variable Attributes, for details of the
1 semantics of attributes applying to variables.  ⇒Type Attributes,
1 for details of the semantics of attributes applying to structure, union
1 and enumerated types.  ⇒Label Attributes, for details of the
11 semantics of attributes applying to labels.  ⇒Enumerator
 Attributes, for details of the semantics of attributes applying to
1 enumerators.  ⇒Statement Attributes, for details of the semantics
1 of attributes applying to statements.
1 
1  An "attribute specifier" is of the form '__attribute__
1 ((ATTRIBUTE-LIST))'.  An "attribute list" is a possibly empty
1 comma-separated sequence of "attributes", where each attribute is one of
1 the following:
1 
1    * Empty.  Empty attributes are ignored.
1 
1    * An attribute name (which may be an identifier such as 'unused', or
1      a reserved word such as 'const').
1 
1    * An attribute name followed by a parenthesized list of parameters
1      for the attribute.  These parameters take one of the following
1      forms:
1 
1         * An identifier.  For example, 'mode' attributes use this form.
1 
1         * An identifier followed by a comma and a non-empty
1           comma-separated list of expressions.  For example, 'format'
1           attributes use this form.
1 
1         * A possibly empty comma-separated list of expressions.  For
1           example, 'format_arg' attributes use this form with the list
1           being a single integer constant expression, and 'alias'
1           attributes use this form with the list being a single string
1           constant.
1 
1  An "attribute specifier list" is a sequence of one or more attribute
1 specifiers, not separated by any other tokens.
1 
1  You may optionally specify attribute names with '__' preceding and
1 following the name.  This allows you to use them in header files without
1 being concerned about a possible macro of the same name.  For example,
1 you may use the attribute name '__noreturn__' instead of 'noreturn'.
1 
1 Label Attributes
1 ................
1 
1 In GNU C, an attribute specifier list may appear after the colon
1 following a label, other than a 'case' or 'default' label.  GNU C++ only
1 permits attributes on labels if the attribute specifier is immediately
1 followed by a semicolon (i.e., the label applies to an empty statement).
1 If the semicolon is missing, C++ label attributes are ambiguous, as it
1 is permissible for a declaration, which could begin with an attribute
1 list, to be labelled in C++.  Declarations cannot be labelled in C90 or
1 C99, so the ambiguity does not arise there.
1 
1 Enumerator Attributes
1 .....................
1 
1 In GNU C, an attribute specifier list may appear as part of an
1 enumerator.  The attribute goes after the enumeration constant, before
1 '=', if present.  The optional attribute in the enumerator appertains to
1 the enumeration constant.  It is not possible to place the attribute
1 after the constant expression, if present.
1 
1 Statement Attributes
1 ....................
1 
1 In GNU C, an attribute specifier list may appear as part of a null
1 statement.  The attribute goes before the semicolon.
1 
1 Type Attributes
1 ...............
1 
1 An attribute specifier list may appear as part of a 'struct', 'union' or
1 'enum' specifier.  It may go either immediately after the 'struct',
1 'union' or 'enum' keyword, or after the closing brace.  The former
1 syntax is preferred.  Where attribute specifiers follow the closing
1 brace, they are considered to relate to the structure, union or
1 enumerated type defined, not to any enclosing declaration the type
1 specifier appears in, and the type defined is not complete until after
1 the attribute specifiers.
1 
1 All other attributes
1 ....................
1 
1 Otherwise, an attribute specifier appears as part of a declaration,
1 counting declarations of unnamed parameters and type names, and relates
1 to that declaration (which may be nested in another declaration, for
1 example in the case of a parameter declaration), or to a particular
1 declarator within a declaration.  Where an attribute specifier is
1 applied to a parameter declared as a function or an array, it should
1 apply to the function or array rather than the pointer to which the
1 parameter is implicitly converted, but this is not yet correctly
1 implemented.
1 
1  Any list of specifiers and qualifiers at the start of a declaration may
1 contain attribute specifiers, whether or not such a list may in that
1 context contain storage class specifiers.  (Some attributes, however,
1 are essentially in the nature of storage class specifiers, and only make
1 sense where storage class specifiers may be used; for example,
1 'section'.)  There is one necessary limitation to this syntax: the first
1 old-style parameter declaration in a function definition cannot begin
1 with an attribute specifier, because such an attribute applies to the
1 function instead by syntax described below (which, however, is not yet
1 implemented in this case).  In some other cases, attribute specifiers
1 are permitted by this grammar but not yet supported by the compiler.
1 All attribute specifiers in this place relate to the declaration as a
1 whole.  In the obsolescent usage where a type of 'int' is implied by the
1 absence of type specifiers, such a list of specifiers and qualifiers may
1 be an attribute specifier list with no other specifiers or qualifiers.
1 
1  At present, the first parameter in a function prototype must have some
1 type specifier that is not an attribute specifier; this resolves an
1 ambiguity in the interpretation of 'void f(int (__attribute__((foo))
1 x))', but is subject to change.  At present, if the parentheses of a
1 function declarator contain only attributes then those attributes are
1 ignored, rather than yielding an error or warning or implying a single
1 parameter of type int, but this is subject to change.
1 
1  An attribute specifier list may appear immediately before a declarator
1 (other than the first) in a comma-separated list of declarators in a
1 declaration of more than one identifier using a single list of
1 specifiers and qualifiers.  Such attribute specifiers apply only to the
1 identifier before whose declarator they appear.  For example, in
1 
1      __attribute__((noreturn)) void d0 (void),
1          __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
1           d2 (void);
1 
1 the 'noreturn' attribute applies to all the functions declared; the
1 'format' attribute only applies to 'd1'.
1 
1  An attribute specifier list may appear immediately before the comma,
1 '=' or semicolon terminating the declaration of an identifier other than
1 a function definition.  Such attribute specifiers apply to the declared
1 object or function.  Where an assembler name for an object or function
1 is specified (⇒Asm Labels), the attribute must follow the 'asm'
1 specification.
1 
1  An attribute specifier list may, in future, be permitted to appear
1 after the declarator in a function definition (before any old-style
1 parameter declarations or the function body).
1 
1  Attribute specifiers may be mixed with type qualifiers appearing inside
1 the '[]' of a parameter array declarator, in the C99 construct by which
1 such qualifiers are applied to the pointer to which the array is
1 implicitly converted.  Such attribute specifiers apply to the pointer,
1 not to the array, but at present this is not implemented and they are
1 ignored.
1 
1  An attribute specifier list may appear at the start of a nested
1 declarator.  At present, there are some limitations in this usage: the
1 attributes correctly apply to the declarator, but for most individual
1 attributes the semantics this implies are not implemented.  When
1 attribute specifiers follow the '*' of a pointer declarator, they may be
1 mixed with any type qualifiers present.  The following describes the
1 formal semantics of this syntax.  It makes the most sense if you are
1 familiar with the formal specification of declarators in the ISO C
1 standard.
1 
1  Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration 'T D1',
1 where 'T' contains declaration specifiers that specify a type TYPE (such
1 as 'int') and 'D1' is a declarator that contains an identifier IDENT.
1 The type specified for IDENT for derived declarators whose type does not
1 include an attribute specifier is as in the ISO C standard.
1 
1  If 'D1' has the form '( ATTRIBUTE-SPECIFIER-LIST D )', and the
1 declaration 'T D' specifies the type "DERIVED-DECLARATOR-TYPE-LIST TYPE"
1 for IDENT, then 'T D1' specifies the type "DERIVED-DECLARATOR-TYPE-LIST
1 ATTRIBUTE-SPECIFIER-LIST TYPE" for IDENT.
1 
1  If 'D1' has the form '* TYPE-QUALIFIER-AND-ATTRIBUTE-SPECIFIER-LIST D',
1 and the declaration 'T D' specifies the type
1 "DERIVED-DECLARATOR-TYPE-LIST TYPE" for IDENT, then 'T D1' specifies the
1 type "DERIVED-DECLARATOR-TYPE-LIST
1 TYPE-QUALIFIER-AND-ATTRIBUTE-SPECIFIER-LIST pointer to TYPE" for IDENT.
1 
1  For example,
1 
1      void (__attribute__((noreturn)) ****f) (void);
1 
1 specifies the type "pointer to pointer to pointer to pointer to
1 non-returning function returning 'void'".  As another example,
1 
1      char *__attribute__((aligned(8))) *f;
1 
1 specifies the type "pointer to 8-byte-aligned pointer to 'char'".  Note
1 again that this does not work with most attributes; for example, the
1 usage of 'aligned' and 'noreturn' attributes given above is not yet
1 supported.
1 
1  For compatibility with existing code written for compiler versions that
1 did not implement attributes on nested declarators, some laxity is
1 allowed in the placing of attributes.  If an attribute that only applies
1 to types is applied to a declaration, it is treated as applying to the
1 type of that declaration.  If an attribute that only applies to
1 declarations is applied to the type of a declaration, it is treated as
1 applying to that declaration; and, for compatibility with code placing
1 the attributes immediately before the identifier declared, such an
1 attribute applied to a function return type is treated as applying to
1 the function type, and such an attribute applied to an array element
1 type is treated as applying to the array type.  If an attribute that
1 only applies to function types is applied to a pointer-to-function type,
1 it is treated as applying to the pointer target type; if such an
1 attribute is applied to a function return type that is not a
1 pointer-to-function type, it is treated as applying to the function
1 type.
1