diff options
Diffstat (limited to 'devdocs/c/language%2F_alignas.html')
| -rw-r--r-- | devdocs/c/language%2F_alignas.html | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/devdocs/c/language%2F_alignas.html b/devdocs/c/language%2F_alignas.html new file mode 100644 index 00000000..ea0b1aa4 --- /dev/null +++ b/devdocs/c/language%2F_alignas.html @@ -0,0 +1,85 @@ + <h1 id="firstHeading" class="firstHeading">_Alignas <span class="t-mark-rev t-since-c11">(since C11)</span>, alignas <span class="t-mark-rev t-since-c23">(since C23)</span> +</h1> <p>Appears in the <a href="declarations" title="c/language/declarations">declaration</a> syntax as one of the type specifiers to modify the <a href="object#Alignment" title="c/language/object">alignment requirement</a> of the object being declared.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>_Alignas</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td> (1) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>alignas</code> <code>(</code> <span class="t-spar">expression</span> <code>)</code> </td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>_Alignas</code> <code>(</code> <span class="t-spar">type</span> <code>)</code> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>alignas</code> <code>(</code> <span class="t-spar">type</span> <code>)</code> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">expression</span> </td> <td> - </td> <td> any <a href="constant_expression" title="c/language/constant expression">integer constant expression</a> whose value is a valid <a href="object#Alignment" title="c/language/object">alignment</a> or zero </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">type</span> </td> <td> - </td> <td> any <a href="type#Type_names" title="c/language/type">type name</a> </td> +</tr> +</table> <table class="t-rev-begin"> <tr class="t-rev t-until-c23"> +<td> <p>The keyword <code>_Alignas</code> is also available as convenience macro <a href="../types" title="c/types"><code>alignas</code></a>, available in the header <a href="../types" title="c/types"><code><stdalign.h></code></a>.</p> +</td> <td><span class="t-mark-rev t-until-c23">(until C23)</span></td> +</tr> </table> <h3 id="Explanation"> Explanation</h3> <p>The <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> specifier can only be used when declaring objects that are not <a href="bit_field" title="c/language/bit field">bit-fields</a>, and don't have the <a href="storage_duration" title="c/language/storage duration">register</a> storage class. It cannot be used in function parameter declarations, and cannot be used in a typedef.</p> +<p>When used in a declaration, the declared object will have its <a href="object#Alignment" title="c/language/object">alignment requirement</a> set to</p> +<div class="t-li1"> +<span class="t-li">1,2)</span> the result of the <span class="t-spar">expression</span>, unless it is zero</div> <div class="t-li1"> +<span class="t-li">3,4)</span> the alignment requirement of <span class="t-spar">type</span>, that is, to <span class="t-rev-inl t-until-c23"><span><code>_Alignof(type)</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignof(type)</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> +</div> <p>except when this would weaken the alignment the type would have had naturally.</p> +<p>If <span class="t-spar">expression</span> evaluates to zero, this specifier has no effect.</p> +<p>When multiple <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> specifiers appear in the same declaration, the strictest one is used.</p> +<p><span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> specifier only needs to appear on the <a href="declarations#Definitions" title="c/language/declarations">definition</a> of an object, but if any declaration uses <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span>, it must specify the same alignment as the <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> on the definition. The behavior is undefined if different translation units specify different alignments for the same object.</p> +<h3 id="Notes"> Notes</h3> <p>In C++, the <code>alignas</code> specifier may also be applied to the declarations of class/struct/union types and enumerations. This is not supported in C, but the alignment of a struct type can be controlled by using <span class="t-rev-inl t-until-c23"><span><code>_Alignas</code></span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span><code>alignas</code></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> in a member declaration.</p> +<h3 id="Keywords"> Keywords</h3> <p><a href="../keyword/alignas" title="c/keyword/alignas"><code>alignas</code></a>, <a href="../keyword/_alignas" title="c/keyword/ Alignas"><code>_Alignas</code></a></p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdalign.h> +#include <stdio.h> + +// every object of type struct sse_t will be aligned to 16-byte boundary +// (note: needs support for DR 444) +struct sse_t +{ + alignas(16) float sse_data[4]; +}; + +// every object of type struct data will be aligned to 128-byte boundary +struct data +{ + char x; + alignas(128) char cacheline[128]; // over-aligned array of char, + // not array of over-aligned chars +}; + +int main(void) +{ + printf("sizeof(data) = %zu (1 byte + 127 bytes padding + 128-byte array)\n", + sizeof(struct data)); + + printf("alignment of sse_t is %zu\n", alignof(struct sse_t)); + + alignas(2048) struct data d; // this instance of data is aligned even stricter + (void)d; // suppresses "maybe unused" warning +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">sizeof(data) = 256 (1 byte + 127 bytes padding + 128-byte array) +alignment of sse_t is 16</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p> +<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th> +</tr> <tr> <td> +<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2396.htm#dr_444">DR 444</a> </td> <td>C11 </td> <td> +<code>_Alignas</code> was not allowed in struct and union members </td> <td>allowed </td> +</tr> +</table> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.7.5 Alignment specifier (p: TBD) </li> +<li> 6.2.8 Alignment of objects (p: TBD) </li> +<li> 7.15 Alignment <stdalign.h> (p: TBD) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 6.7.5 Alignment specifier (p: 92) </li> +<li> 6.2.8 Alignment of objects (p: 36-37) </li> +<li> 7.15 Alignment <stdalign.h> (p: 196) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 6.7.5 Alignment specifier (p: 127-128) </li> +<li> 6.2.8 Alignment of objects (p: 48-49) </li> +<li> 7.15 Alignment <stdalign.h> (p: 268) </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/alignas" title="cpp/language/alignas">C++ documentation</a></span> for <span class=""><span><code>alignas</code> specifier</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/language/_Alignas" class="_attribution-link">https://en.cppreference.com/w/c/language/_Alignas</a> + </p> +</div> |