gcc/doc/gcc/extensions-to-the-c-language-family/attribute-syntax.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: attribute syntax
   7
   8 .. _attribute-syntax:
   9
  10 Attribute Syntax
  11 ****************
  12
  13 This section describes the syntax with which ``__attribute__`` may be
  14 used, and the constructs to which attribute specifiers bind, for the C
  15 language.  Some details may vary for C++ and Objective-C.  Because of
  16 infelicities in the grammar for attributes, some forms described here
  17 may not be successfully parsed in all cases.
  18
  19 There are some problems with the semantics of attributes in C++.  For
  20 example, there are no manglings for attributes, although they may affect
  21 code generation, so problems may arise when attributed types are used in
  22 conjunction with templates or overloading.  Similarly, ``typeid``
  23 does not distinguish between types with different attributes.  Support
  24 for attributes in C++ may be restricted in future to attributes on
  25 declarations only, but not on nested declarators.
  26
  27 See :ref:`function-attributes`, for details of the semantics of attributes
  28 applying to functions.  See :ref:`variable-attributes`, for details of the
  29 semantics of attributes applying to variables.  See :ref:`type-attributes`,
  30 for details of the semantics of attributes applying to structure, union
  31 and enumerated types.
  32 See :ref:`label-attributes`, for details of the semantics of attributes
  33 applying to labels.
  34 See :ref:`enumerator-attributes`, for details of the semantics of attributes
  35 applying to enumerators.
  36 See :ref:`statement-attributes`, for details of the semantics of attributes
  37 applying to statements.
  38
  39 An :dfn:`attribute specifier` is of the form
  40 ``__attribute__ ((attribute-list))``.  An :dfn:`attribute list`
  41 is a possibly empty comma-separated sequence of :dfn:`attributes`, where
  42 each attribute is one of the following:
  43
  44 * Empty.  Empty attributes are ignored.
  45
  46 * An attribute name
  47   (which may be an identifier such as :fn-attr:`unused`, or a reserved
  48   word such as :fn-attr:`const`).
  49
  50 * An attribute name followed by a parenthesized list of
  51   parameters for the attribute.
  52   These parameters take one of the following forms:
  53
  54   * An identifier.  For example, ``mode`` attributes use this form.
  55
  56   * An identifier followed by a comma and a non-empty comma-separated list
  57     of expressions.  For example, ``format`` attributes use this form.
  58
  59   * A possibly empty comma-separated list of expressions.  For example,
  60     ``format_arg`` attributes use this form with the list being a single
  61     integer constant expression, and ``alias`` attributes use this form
  62     with the list being a single string constant.
  63
  64 An :dfn:`attribute specifier list` is a sequence of one or more attribute
  65 specifiers, not separated by any other tokens.
  66
  67 You may optionally specify attribute names with :samp:`__`
  68 preceding and following the name.
  69 This allows you to use them in header files without
  70 being concerned about a possible macro of the same name.  For example,
  71 you may use the attribute name ``__noreturn__`` instead of :fn-attr:`noreturn`.
  72
  73 Label Attributes
  74 ^^^^^^^^^^^^^^^^
  75
  76 In GNU C, an attribute specifier list may appear after the colon following a
  77 label, other than a ``case`` or ``default`` label.  GNU C++ only permits
  78 attributes on labels if the attribute specifier is immediately
  79 followed by a semicolon (i.e., the label applies to an empty
  80 statement).  If the semicolon is missing, C++ label attributes are
  81 ambiguous, as it is permissible for a declaration, which could begin
  82 with an attribute list, to be labelled in C++.  Declarations cannot be
  83 labelled in C90 or C99, so the ambiguity does not arise there.
  84
  85 Enumerator Attributes
  86 ^^^^^^^^^^^^^^^^^^^^^
  87
  88 In GNU C, an attribute specifier list may appear as part of an enumerator.
  89 The attribute goes after the enumeration constant, before ``=``, if
  90 present.  The optional attribute in the enumerator appertains to the
  91 enumeration constant.  It is not possible to place the attribute after
  92 the constant expression, if present.
  93
  94 Statement Attributes
  95 ^^^^^^^^^^^^^^^^^^^^
  96
  97 In GNU C, an attribute specifier list may appear as part of a null
  98 statement.  The attribute goes before the semicolon.
  99
 100 Type Attributes
 101 ^^^^^^^^^^^^^^^
 102
 103 An attribute specifier list may appear as part of a ``struct``,
 104 ``union`` or ``enum`` specifier.  It may go either immediately
 105 after the ``struct``, ``union`` or ``enum`` keyword, or after
 106 the closing brace.  The former syntax is preferred.
 107 Where attribute specifiers follow the closing brace, they are considered
 108 to relate to the structure, union or enumerated type defined, not to any
 109 enclosing declaration the type specifier appears in, and the type
 110 defined is not complete until after the attribute specifiers.
 111
 112 .. Otherwise, there would be the following problems: a shift/reduce
 113
 114 .. conflict between attributes binding the struct/union/enum and
 115
 116 .. binding to the list of specifiers/qualifiers; and "aligned"
 117
 118 .. attributes could use sizeof for the structure, but the size could be
 119
 120 .. changed later by "packed" attributes.
 121
 122 All other attributes
 123 ^^^^^^^^^^^^^^^^^^^^
 124
 125 Otherwise, an attribute specifier appears as part of a declaration,
 126 counting declarations of unnamed parameters and type names, and relates
 127 to that declaration (which may be nested in another declaration, for
 128 example in the case of a parameter declaration), or to a particular declarator
 129 within a declaration.  Where an
 130 attribute specifier is applied to a parameter declared as a function or
 131 an array, it should apply to the function or array rather than the
 132 pointer to which the parameter is implicitly converted, but this is not
 133 yet correctly implemented.
 134
 135 Any list of specifiers and qualifiers at the start of a declaration may
 136 contain attribute specifiers, whether or not such a list may in that
 137 context contain storage class specifiers.  (Some attributes, however,
 138 are essentially in the nature of storage class specifiers, and only make
 139 sense where storage class specifiers may be used; for example,
 140 ``section``.)  There is one necessary limitation to this syntax: the
 141 first old-style parameter declaration in a function definition cannot
 142 begin with an attribute specifier, because such an attribute applies to
 143 the function instead by syntax described below (which, however, is not
 144 yet implemented in this case).  In some other cases, attribute
 145 specifiers are permitted by this grammar but not yet supported by the
 146 compiler.  All attribute specifiers in this place relate to the
 147 declaration as a whole.  In the obsolescent usage where a type of
 148 ``int`` is implied by the absence of type specifiers, such a list of
 149 specifiers and qualifiers may be an attribute specifier list with no
 150 other specifiers or qualifiers.
 151
 152 At present, the first parameter in a function prototype must have some
 153 type specifier that is not an attribute specifier; this resolves an
 154 ambiguity in the interpretation of ``void f(int
 155 (__attribute__((foo)) x))``, but is subject to change.  At present, if
 156 the parentheses of a function declarator contain only attributes then
 157 those attributes are ignored, rather than yielding an error or warning
 158 or implying a single parameter of type int, but this is subject to
 159 change.
 160
 161 An attribute specifier list may appear immediately before a declarator
 162 (other than the first) in a comma-separated list of declarators in a
 163 declaration of more than one identifier using a single list of
 164 specifiers and qualifiers.  Such attribute specifiers apply
 165 only to the identifier before whose declarator they appear.  For
 166 example, in
 167
 168 .. code-block:: c++
 169
 170   __attribute__((noreturn)) void d0 (void),
 171       __attribute__((format(printf, 1, 2))) d1 (const char *, ...),
 172        d2 (void);
 173
 174 the :fn-attr:`noreturn` attribute applies to all the functions
 175 declared; the ``format`` attribute only applies to ``d1``.
 176
 177 An attribute specifier list may appear immediately before the comma,
 178 ``=`` or semicolon terminating the declaration of an identifier other
 179 than a function definition.  Such attribute specifiers apply
 180 to the declared object or function.  Where an
 181 assembler name for an object or function is specified (see :ref:`asm-labels`), the attribute must follow the ``asm``
 182 specification.
 183
 184 An attribute specifier list may, in future, be permitted to appear after
 185 the declarator in a function definition (before any old-style parameter
 186 declarations or the function body).
 187
 188 Attribute specifiers may be mixed with type qualifiers appearing inside
 189 the ``[]`` of a parameter array declarator, in the C99 construct by
 190 which such qualifiers are applied to the pointer to which the array is
 191 implicitly converted.  Such attribute specifiers apply to the pointer,
 192 not to the array, but at present this is not implemented and they are
 193 ignored.
 194
 195 An attribute specifier list may appear at the start of a nested
 196 declarator.  At present, there are some limitations in this usage: the
 197 attributes correctly apply to the declarator, but for most individual
 198 attributes the semantics this implies are not implemented.
 199 When attribute specifiers follow the ``*`` of a pointer
 200 declarator, they may be mixed with any type qualifiers present.
 201 The following describes the formal semantics of this syntax.  It makes the
 202 most sense if you are familiar with the formal specification of
 203 declarators in the ISO C standard.
 204
 205 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration ``T
 206 D1``, where ``T`` contains declaration specifiers that specify a type
 207 :samp:`{Type}` (such as ``int``) and ``D1`` is a declarator that
 208 contains an identifier :samp:`{ident}`.  The type specified for :samp:`{ident}`
 209 for derived declarators whose type does not include an attribute
 210 specifier is as in the ISO C standard.
 211
 212 If ``D1`` has the form ``( attribute-specifier-list D )``,
 213 and the declaration ``T D`` specifies the type
 214 ' :samp:`{derived-declarator-type-list}` :samp:`{Type}` ' for :samp:`{ident}`, then
 215 ``T D1`` specifies the type ' :samp:`{derived-declarator-type-list}`
 216 :samp:`{attribute-specifier-list}` :samp:`{Type}` ' for :samp:`{ident}`.
 217
 218 If ``D1`` has the form ``*
 219 type-qualifier-and-attribute-specifier-list D``, and the
 220 declaration ``T D`` specifies the type
 221 ' :samp:`{derived-declarator-type-list}` :samp:`{Type}` ' for :samp:`{ident}`, then
 222 ``T D1`` specifies the type ' :samp:`{derived-declarator-type-list}`
 223 :samp:`{type-qualifier-and-attribute-specifier-list}` pointer to :samp:`{Type}` ' for
 224 :samp:`{ident}`.
 225
 226 For example,
 227
 228 .. code-block:: c++
 229
 230   void (__attribute__((noreturn)) ****f) (void);
 231
 232 specifies the type 'pointer to pointer to pointer to pointer to
 233 non-returning function returning ``void`` '.  As another example,
 234
 235 .. code-block:: c++
 236
 237   char *__attribute__((aligned(8))) *f;
 238
 239 specifies the type 'pointer to 8-byte-aligned pointer to ``char`` '.
 240 Note again that this does not work with most attributes; for example,
 241 the usage of :samp:`aligned` and :samp:`noreturn` attributes given above
 242 is not yet supported.
 243
 244 For compatibility with existing code written for compiler versions that
 245 did not implement attributes on nested declarators, some laxity is
 246 allowed in the placing of attributes.  If an attribute that only applies
 247 to types is applied to a declaration, it is treated as applying to
 248 the type of that declaration.  If an attribute that only applies to
 249 declarations is applied to the type of a declaration, it is treated
 250 as applying to that declaration; and, for compatibility with code
 251 placing the attributes immediately before the identifier declared, such
 252 an attribute applied to a function return type is treated as
 253 applying to the function type, and such an attribute applied to an array
 254 element type is treated as applying to the array type.  If an
 255 attribute that only applies to function types is applied to a
 256 pointer-to-function type, it is treated as applying to the pointer
 257 target type; if such an attribute is applied to a function return type
 258 that is not a pointer-to-function type, it is treated as applying
 259 to the function type.