devdocs/c/language%2Fattributes.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

    <h1 id="firstHeading" class="firstHeading">Attribute specifier sequence<span class="t-mark-rev t-since-c23">(since C23)</span>
</h1>            <p>Introduces implementation-defined attributes for types, objects, expressions, etc.</p>
<h3 id="Syntax"> Syntax</h3> <code>[[</code><span class="t-spar">attr</span> <code>]]</code> <code>[[</code><span class="t-spar">attr1</span>, <span class="t-spar">attr2</span>, <span class="t-spar">attr3</span><code>(</code><span class="t-spar">args</span><code>)</code><code>]]</code> <code>[[</code><span class="t-spar">attribute-prefix</span><code>::</code><span class="t-spar">attr</span> <code>(</code><span class="t-spar">args</span><code>)</code><code>]]</code>  <p>Formally, the syntax is</p>
<table class="t-sdsc-begin">  <tr class="t-sdsc"> <td> <code>[[</code> <span class="t-spar">attribute-list</span> <code>]]</code> </td> <td class="t-sdsc-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td>
</tr> 
</table> <p>where <span class="t-spar">attribute-list</span> is a comma-separated sequence of zero or more <span class="t-spar">attribute-token</span> s</p>
<table class="t-sdsc-begin">  <tr class="t-sdsc"> <td> <span class="t-spar">standard-attribute</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td>
</tr>  <tr class="t-sdsc"> <td> <span class="t-spar">attribute-prefix</span> <code>::</code> <span class="t-spar">identifier</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td>
</tr>  <tr class="t-sdsc"> <td> <span class="t-spar">standard-attribute</span> <code>(</code> <span class="t-spar">argument-list</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td>
</tr>  <tr class="t-sdsc"> <td> <span class="t-spar">attribute-prefix</span> <code>::</code> <span class="t-spar">identifier</span> <code>(</code> <span class="t-spar">argument-list</span> <span class="t-mark">(optional)</span> <code>)</code> </td> <td> (4) </td> <td class="t-sdsc-nopad"> </td>
</tr> 
</table> <p>where <span class="t-spar">attribute-prefix</span> is an <span class="t-spar">identifier</span> and <span class="t-spar">argument-list</span> is a sequence of tokens where parentheses, brackets and braces are balanced (<span class="t-spar">balanced-token-sequence</span>).</p>
<div class="t-li1">
<span class="t-li">1)</span> standard attribute, such as <span class="t-cc"><span class="br0">[</span><span class="br0">[</span>fallthrough<span class="br0">]</span><span class="br0">]</span></span>
</div> <div class="t-li1">
<span class="t-li">2)</span> attribute with a namespace, such as <span class="t-cc"><span class="br0">[</span><span class="br0">[</span>gnu<span class="sy4">::</span><span class="me2">unused</span><span class="br0">]</span><span class="br0">]</span></span>
</div> <div class="t-li1">
<span class="t-li">3)</span> standard attribute with arguments, such as <span class="t-cc"><span class="br0">[</span><span class="br0">[</span>deprecated<span class="br0">(</span><span class="st0">"reason"</span><span class="br0">)</span><span class="br0">]</span><span class="br0">]</span></span>
</div> <div class="t-li1">
<span class="t-li">4)</span> attribute with both a namespace and an argument list, such as <span class="t-cc"><span class="br0">[</span><span class="br0">[</span>gnu<span class="sy4">::</span><span class="me2">nonnull</span><span class="br0">(</span><span class="nu0">1</span><span class="br0">)</span><span class="br0">]</span><span class="br0">]</span></span>
</div> <h3 id="Explanation"> Explanation</h3> <p>Attributes provide the unified standard syntax for implementation-defined language extensions, such as the GNU and IBM language extensions <code>__attribute__((...))</code>, Microsoft extension <code>__declspec()</code>, etc.</p>
<p>An attribute can be used almost everywhere in the C program, and can be applied to almost everything: to types, to variables, to functions, to names, to code blocks, to entire translation units, although each particular attribute is only valid where it is permitted by the implementation: <code>[[expect_true]]</code> could be an attribute that can only be used with an <code>if</code>, and not with a class declaration. <code>[[omp::parallel()]]</code> could be an attribute that applies to a code block or to a <code>for</code> loop, but not to the type <code>int</code>, etc. (note these two attributes are fictional examples, see below for the standard and some non-standard attributes)</p>
<p>In declarations, attributes may appear both before the whole declaration and directly after the name of the entity that is declared, in which case they are combined. In most other situations, attributes apply to the directly preceding entity.</p>
<p>Two consecutive left square bracket tokens (<code>[[</code>) may only appear when introducing an attribute-specifier or inside an attribute argument.</p>
<p>Besides the standard attributes listed below, implementations may support arbitrary non-standard attributes with implementation-defined behavior. All attributes unknown to an implementation are ignored without causing an error.</p>
<p>Every <span class="t-spar">standard-attribute</span> is reserved for standardization. That is, every non-standard attribute is prefixed by a <span class="t-spar">attribute-prefix</span> provided by the implementation, e.g. <code>[[gnu::may_alias]]</code> and <code>[[clang::no_sanitize]]</code>.</p>
<h3 id="Standard_attributes"> Standard attributes</h3> <p>Only the following attributes are defined by the C standard. Every standard attribute whose name is of form <code>attr</code> can be also spelled as <code>__attr__</code> and its meaning is not changed.</p>
<table class="t-dsc-begin"> <tr class="t-dsc"> <td> <code>[[<a href="attributes/deprecated" title="c/language/attributes/deprecated">deprecated</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span><br><code>[[<a href="attributes/deprecated" title="c/language/attributes/deprecated">deprecated</a>("<i>reason</i>")]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> indicates that the use of the name or entity declared with this attribute is allowed, but discouraged for some <span class="t-spar">reason</span><br><span class="t-mark">(attribute specifier)</span> </td>
</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/fallthrough" title="c/language/attributes/fallthrough">fallthrough</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> indicates that the fall through from the previous case label is intentional and should not be diagnosed by a compiler that warns on fall-through<br><span class="t-mark">(attribute specifier)</span> </td>
</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/nodiscard" title="c/language/attributes/nodiscard">nodiscard</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span><br><code>[[<a href="attributes/nodiscard" title="c/language/attributes/nodiscard">nodiscard</a>("<i>reason</i>")]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> encourages the compiler to issue a warning if the return value is discarded<br><span class="t-mark">(attribute specifier)</span> </td>
</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/maybe_unused" title="c/language/attributes/maybe unused">maybe_unused</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> suppresses compiler warnings on unused entities, if any<br><span class="t-mark">(attribute specifier)</span> </td>
</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">noreturn</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span><br><code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">_Noreturn</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span><span class="t-mark">(deprecated)</span> </td> <td> indicates that the function does not return<br><span class="t-mark">(attribute specifier)</span> </td>
</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/unsequenced" title="c/language/attributes/unsequenced">unsequenced</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> indicates that a function is stateless, effectless, idempotent and independent<br><span class="t-mark">(attribute specifier)</span> </td>
</tr> <tr class="t-dsc"> <td> <code>[[<a href="attributes/reproducible" title="c/language/attributes/reproducible" class="mw-redirect">reproducible</a>]]</code><span class="t-mark-rev t-since-c23">(C23)</span> </td> <td> indicates that a function is effectless and idempotent<br><span class="t-mark">(attribute specifier)</span> </td>
</tr> </table> <h3 id="Attribute_testing"> Attribute testing</h3> <table class="t-sdsc-begin">  <tr class="t-sdsc"> <td class="t-sdsc-nopad"> <code>__has_c_attribute(</code> <span class="t-spar">attribute-token</span> <code>)</code> </td> <td class="t-sdsc-nopad"> </td> <td class="t-sdsc-nopad"> </td>
</tr> 
</table> <p>Checks for the presence of an attribute token named by <span class="t-spar">attribute-token</span>.</p>
<p>For standard attributes, it will expand to the year and month in which the attribute was added to the working draft (see table below), the presence of vendor-specific attributes is determined by a non-zero integer constant.</p>
<p><code>__has_c_attribute</code> can be expanded in the expression of <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #if</code></a> and <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #elif</code></a>. It is treated as a defined macro by <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #ifdef</code></a>, <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code> #ifndef</code></a> and <a href="../preprocessor/conditional" title="c/preprocessor/conditional"><code>defined</code></a> but cannot be used anywhere else.</p>
<table class="wikitable sortable"> <tr> <th> <span class="t-spar">attribute-token</span> </th> <th> Attribute </th> <th> Value </th> <th> <span title="Standard in which the feature is introduced">Standard</span> </th>
</tr> <tr> <td>
<code>deprecated</code> </td> <td>
<code>[[<a href="attributes/deprecated" title="c/language/attributes/deprecated">deprecated</a>]]</code> </td> <td>
<code>201904L</code> </td> <td>
<span class="t-mark-rev t-since-c23">(C23)</span> </td>
</tr> <tr> <td>
<code>fallthrough</code> </td> <td>
<code>[[<a href="attributes/fallthrough" title="c/language/attributes/fallthrough">fallthrough</a>]]</code> </td> <td>
<code>201904L</code> </td> <td>
<span class="t-mark-rev t-since-c23">(C23)</span> </td>
</tr> <tr> <td>
<code>maybe_unused</code> </td> <td>
<code>[[<a href="attributes/maybe_unused" title="c/language/attributes/maybe unused">maybe_unused</a>]]</code> </td> <td>
<code>201904L</code> </td> <td>
<span class="t-mark-rev t-since-c23">(C23)</span> </td>
</tr> <tr> <td>
<code>nodiscard</code> </td> <td>
<code>[[<a href="attributes/nodiscard" title="c/language/attributes/nodiscard">nodiscard</a>]]</code> </td> <td>
<code>202003L</code> </td> <td>
<span class="t-mark-rev t-since-c23">(C23)</span> </td>
</tr> <tr> <td>
<code>noreturn</code><br><code>_Noreturn</code> </td> <td>
<code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">noreturn</a>]]</code><br><code>[[<a href="attributes/noreturn" title="c/language/attributes/noreturn">_Noreturn</a>]]</code> </td> <td>
<code>202202L</code> </td> <td>
<span class="t-mark-rev t-since-c23">(C23)</span> </td>
</tr> <tr> <td>
<code>unsequenced</code> </td> <td>
<code>[[<a href="attributes/unsequenced" title="c/language/attributes/unsequenced">unsequenced</a>]]</code> </td> <td>
<code>202207L</code> </td> <td>
<span class="t-mark-rev t-since-c23">(C23)</span> </td>
</tr> <tr> <td>
<code>reproducible</code> </td> <td>
<code>[[<a href="attributes/reproducible" title="c/language/attributes/reproducible" class="mw-redirect">reproducible</a>]]</code> </td> <td>
<code>202207L</code> </td> <td>
<span class="t-mark-rev t-since-c23">(C23)</span> </td>
</tr>
</table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">[[gnu::hot]] [[gnu::const]] [[nodiscard]]
int f(void); // declare f with three attributes
 
[[gnu::const, gnu::hot, nodiscard]]
int f(void); // the same as above, but uses a single attr
             // specifier that contains three attributes
 
int f(void) { return 0; }
 
int main(void)
{
}</pre></div> </div> <h3 id="References"> References</h3>  <ul>
<li> C23 standard (ISO/IEC 9899:2023): </li>
<ul><li> 6.7.12 Attributes (p: TBD) </li></ul>
</ul>   <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/language/attributes" title="cpp/language/attributes">C++ documentation</a></span> for <span class=""><span>Attribute specifier sequence</span></span> </td>
</tr> </table> <h3 id="External_links"> External links</h3> <table> <tr style="vertical-align:top;"> <td>1. </td> <td>
<a rel="nofollow" class="external text" href="https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html#Attribute-Syntax">Attributes in GCC</a> </td>
</tr> <tr style="vertical-align:top;"> <td>2. </td> <td>
<a rel="nofollow" class="external text" href="https://clang.llvm.org/docs/AttributeReference.html">Attributes in Clang</a> </td>
</tr>
</table>           <div class="_attribution">
  <p class="_attribution-p">
    &copy; cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br>
    <a href="https://en.cppreference.com/w/c/language/attributes" class="_attribution-link">https://en.cppreference.com/w/c/language/attributes</a>
  </p>
</div>