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