]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
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 | |
3ed1b4ce | 259 | to the function type. |