new repository

1 files changed, 79 insertions, 0 deletions

diff --git a/devdocs/c/program%2Funreachable.html b/devdocs/c/program%2Funreachable.html
new file mode 100644
index 00000000..09e33e03
--- /dev/null
+++ b/devdocs/c/program%2Funreachable.html
@@ -0,0 +1,79 @@
+    <h1 id="firstHeading" class="firstHeading">unreachable</h1>            <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code>&lt;stddef.h&gt;</code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl t-since-c23"> <td> <pre data-language="c">#define unreachable() /* see below */</pre>
+</td> <td class="t-dcl-nopad"> </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> </tr>  </table> <p>The function-like macro <code>unreachable</code> expands to a <code>void</code> expression. Executing <code>unreachable()</code> results in <a href="../language/behavior" title="c/language/behavior">undefined behavior</a>.</p>
+<p>An implementation may use this to optimize impossible code branches away (typically, in optimized builds) or to trap them to prevent further execution (typically, in debug builds).</p>
+<h3 id="Possible_implementation"> Possible implementation</h3> <table class="eq-fun-cpp-table"> <tr> <td> <div class="c source-c"><pre data-language="c">// Uses compiler specific extensions if possible.
+#ifdef __GNUC__ // GCC, Clang, ICC
+ 
+#define unreachable() (__builtin_unreachable())
+ 
+#elifdef _MSC_VER // MSVC
+ 
+#define unreachable() (__assume(false))
+ 
+#else
+// Even if no extension is used, undefined behavior is still raised by
+// the empty function body and the noreturn attribute.
+ 
+// The external definition of unreachable_impl must be emitted in a separated TU
+// due to the rule for inline functions in C.
+ 
+[[noreturn]] inline void unreachable_impl() {}
+#define unreachable() (unreachable_impl())
+ 
+#endif</pre></div> </td>
+</tr>
+</table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include &lt;assert.h&gt;
+#include &lt;stddef.h&gt;
+#include &lt;stdint.h&gt;
+#include &lt;stdlib.h&gt;
+ 
+struct Color { uint8_t r, g, b, a; };
+struct ColorSpan { struct Color* data; size_t size; };
+ 
+// Assume that only restricted set of texture caps is supported.
+struct ColorSpan allocate_texture(size_t xy)
+{
+    switch (xy)
+    {
+    case 128: [[fallthrough]];
+    case 256: [[fallthrough]];
+    case 512:
+    {
+        /* ... */
+        struct ColorSpan result = {
+            .data = malloc(xy * xy * sizeof(struct Color)),
+            .size = xy * xy
+        };
+        if (!result.data)
+            result.size = 0;
+        return result;
+    }
+    default:
+        unreachable();
+    }
+}
+ 
+int main(void)
+{
+    struct ColorSpan tex = allocate_texture(128); // OK
+    assert(tex.size == 128 * 128);
+ 
+    struct ColorSpan badtex = allocate_texture(32);  // Undefined behavior
+ 
+    free(badtex.data);
+    free(tex.data);
+}</pre></div> <p>Possible output:</p>
+<div class="text source-text"><pre data-language="c">Segmentation fault</pre></div> </div> <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/utility/unreachable" title="cpp/utility/unreachable">C++ documentation</a></span> for <code>unreachable</code> </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/Other-Builtins.html#index-_005f_005fbuiltin_005funreachable">GCC docs: <code>__builtin_unreachable</code></a> </td>
+</tr> <tr style="vertical-align:top;"> <td>2. </td> <td>
+<a rel="nofollow" class="external text" href="https://clang.llvm.org/docs/LanguageExtensions.html#builtin-unreachable">Clang docs: <code>__builtin_unreachable</code></a> </td>
+</tr> <tr style="vertical-align:top;"> <td>3. </td> <td>
+<a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/intrinsics/assume">MSVC docs: <code>__assume</code></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/program/unreachable" class="_attribution-link">https://en.cppreference.com/w/c/program/unreachable</a>
+  </p>
+</div>