docs/LanguageExtensions.html

   1 <html>
   2 <head>
   3 <title>Clang Language Extensions</title>
   4 <link type="text/css" rel="stylesheet" href="../menu.css" />
   5 <link type="text/css" rel="stylesheet" href="../content.css" />
   6 <style type="text/css">
   7 td {
   8         vertical-align: top;
   9 }
  10 </style>
  11 </head>
  12 <body>
  13
  14 <!--#include virtual="../menu.html.incl"-->
  15
  16 <div id="content">
  17
  18 <h1>Clang Language Extensions</h1>
  19
  20 <ul>
  21 <li><a href="#intro">Introduction</a></li>
  22 <li><a href="#feature_check">Feature Checking Macros</a></li>
  23 <li><a href="#has_include">Include File Checking Macros</a></li>
  24 <li><a href="#builtinmacros">Builtin Macros</a></li>
  25 <li><a href="#vectors">Vectors and Extended Vectors</a></li>
  26 <li><a href="#checking_language_features">Checks for Standard Language Features</a></li>
  27   <ul>
  28   <li><a href="#cxx_exceptions">C++ exceptions</a></li>
  29   <li><a href="#cxx_rtti">C++ RTTI</a></li>
  30   </ul>
  31 <li><a href="#checking_upcoming_features">Checks for Upcoming Standard Language Features</a></li>
  32   <ul>
  33   <li><a href="#cxx_attributes">C++0x attributes</a></li>
  34   <li><a href="#cxx_decltype">C++0x <tt>decltype()</tt></a></li>
  35   <li><a href="#cxx_deleted_functions">C++0x deleted functions</a></li>
  36   <li><a href="#cxx_concepts">C++ TR concepts</a></li>
  37   <li><a href="#cxx_lambdas">C++0x lambdas</a></li>
  38   <li><a href="#cxx_nullptr">C++0x nullptr</a></li>
  39   <li><a href="#cxx_rvalue_references">C++0x rvalue references</a></li>
  40   <li><a href="#cxx_static_assert">C++0x <tt>static_assert()</tt></a></li>
  41   <li><a href="#cxx_auto_type">C++0x type inference</a></li>
  42   <li><a href="#cxx_variadic_templates">C++0x variadic templates</a></li>
  43   </ul>
  44 <li><a href="#blocks">Blocks</a></li>
  45 <li><a href="#overloading-in-c">Function Overloading in C</a></li>
  46 <li><a href="#builtins">Builtin Functions</a>
  47   <ul>
  48   <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
  49   <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li>
  50   </ul>
  51 </li>
  52 <li><a href="#targetspecific">Target-Specific Extensions</a>
  53   <ul>
  54   <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li>
  55   </ul>
  56 </li>
  57 <li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a>
  58   <ul>
  59     <li><a href="#analyzerattributes">Analyzer Attributes</a></li>
  60   </ul>
  61 </li>
  62 </ul>
  63
  64 <!-- ======================================================================= -->
  65 <h2 id="intro">Introduction</h2>
  66 <!-- ======================================================================= -->
  67
  68 <p>This document describes the language extensions provided by Clang.  In
  69 addition to the language extensions listed here, Clang aims to support a broad
  70 range of GCC extensions.  Please see the <a
  71 href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
  72 more information on these extensions.</p>
  73
  74 <!-- ======================================================================= -->
  75 <h2 id="feature_check">Feature Checking Macros</h2>
  76 <!-- ======================================================================= -->
  77
  78 <p>Language extensions can be very useful, but only if you know you can depend
  79 on them.  In order to allow fine-grain features checks, we support two builtin
  80 function-like macros.  This allows you to directly test for a feature in your
  81 code without having to resort to something like autoconf or fragile "compiler
  82 version checks".</p>
  83
  84 <!-- ======================================================================= -->
  85 <h3 id="__has_builtin">__has_builtin</h3>
  86 <!-- ======================================================================= -->
  87
  88 <p>This function-like macro takes a single identifier argument that is the name
  89 of a builtin function.  It evaluates to 1 if the builtin is supported or 0 if
  90 not.  It can be used like this:</p>
  91
  92 <blockquote>
  93 <pre>
  94 #ifndef __has_builtin         // Optional of course.
  95   #define __has_builtin(x) 0  // Compatibility with non-clang compilers.
  96 #endif
  97
  98 ...
  99 #if __has_builtin(__builtin_trap)
 100   __builtin_trap();
 101 #else
 102   abort();
 103 #endif
 104 ...
 105 </pre>
 106 </blockquote>
 107
 108
 109 <!-- ======================================================================= -->
 110 <h3 id="__has_feature">__has_feature</h3>
 111 <!-- ======================================================================= -->
 112
 113 <p>This function-like macro takes a single identifier argument that is the name
 114 of a feature.  It evaluates to 1 if the feature is supported or 0 if not.  It
 115 can be used like this:</p>
 116
 117 <blockquote>
 118 <pre>
 119 #ifndef __has_feature         // Optional of course.
 120   #define __has_feature(x) 0  // Compatibility with non-clang compilers.
 121 #endif
 122
 123 ...
 124 #if __has_feature(attribute_overloadable) || \
 125     __has_feature(blocks)
 126 ...
 127 #endif
 128 ...
 129 </pre>
 130 </blockquote>
 131
 132 <p>The feature tag is described along with the language feature below.</p>
 133
 134 <!-- ======================================================================= -->
 135 <h2 id="has_include">Include File Checking Macros</h2>
 136 <!-- ======================================================================= -->
 137
 138 <p>Not all developments systems have the same include files.
 139 The <a href="#__has_include">__has_include</a> and
 140 <a href="#__has_include_next">__has_include_next</a> macros allow you to
 141 check for the existence of an include file before doing
 142 a possibly failing #include directive.</p>
 143
 144 <!-- ======================================================================= -->
 145 <h3 id="__has_include">__has_include</h3>
 146 <!-- ======================================================================= -->
 147
 148 <p>This function-like macro takes a single file name string argument that
 149 is the name of an include file.  It evaluates to 1 if the file can
 150 be found using the include paths, or 0 otherwise:</p>
 151
 152 <blockquote>
 153 <pre>
 154 // Note the two possible file name string formats.
 155 #if __has_include("myinclude.h") && __has_include(&lt;stdint.h&gt;)
 156 # include "myinclude.h"
 157 #endif
 158
 159 // To avoid problem with non-clang compilers not having this macro.
 160 #if defined(__has_include) && __has_include("myinclude.h")
 161 # include "myinclude.h"
 162 #endif
 163 </pre>
 164 </blockquote>
 165
 166 <p>To test for this feature, use #if defined(__has_include).</p>
 167
 168 <!-- ======================================================================= -->
 169 <h3 id="__has_include_next">__has_include_next</h3>
 170 <!-- ======================================================================= -->
 171
 172 <p>This function-like macro takes a single file name string argument that
 173 is the name of an include file.  It is like __has_include except that it
 174 looks for the second instance of the given file found in the include
 175 paths.  It evaluates to 1 if the second instance of the file can
 176 be found using the include paths, or 0 otherwise:</p>
 177
 178 <blockquote>
 179 <pre>
 180 // Note the two possible file name string formats.
 181 #if __has_include_next("myinclude.h") && __has_include_next(&lt;stdint.h&gt;)
 182 # include_next "myinclude.h"
 183 #endif
 184
 185 // To avoid problem with non-clang compilers not having this macro.
 186 #if defined(__has_include_next) && __has_include_next("myinclude.h")
 187 # include_next "myinclude.h"
 188 #endif
 189 </pre>
 190 </blockquote>
 191
 192 <p>Note that __has_include_next, like the GNU extension
 193 #include_next directive, is intended for use in headers only,
 194 and will issue a warning if used in the top-level compilation
 195 file.  A warning will also be issued if an absolute path
 196 is used in the file argument.</p>
 197
 198 <!-- ======================================================================= -->
 199 <h2 id="builtinmacros">Builtin Macros</h2>
 200 <!-- ======================================================================= -->
 201
 202 <dl>
 203   <dt><code>__BASE_FILE__</code></dt>
 204   <dd>Defined to a string that contains the name of the main input
 205   file passed to Clang.</dd>
 206
 207   <dt><code>__COUNTER__</code></dt>
 208   <dd>Defined to an integer value that starts at zero and is
 209   incremented each time the <code>__COUNTER__</code> macro is
 210   expanded.</dd>
 211
 212   <dt><code>__INCLUDE_LEVEL__</code></dt>
 213   <dd>Defined to an integral value that is the include depth of the
 214   file currently being translated. For the main file, this value is
 215   zero.</dd>
 216
 217   <dt><code>__TIMESTAMP__</code></dt>
 218   <dd>Defined to the date and time of the last modification of the
 219   current source file.</dd>
 220
 221   <dt><code>__clang__</code></dt>
 222   <dd>Defined when compiling with Clang</dd>
 223
 224   <dt><code>__clang_major__</code></dt>
 225   <dd>Defined to the major version number of Clang (e.g., the 2 in
 226   2.0.1).</dd>
 227
 228   <dt><code>__clang_minor__</code></dt>
 229   <dd>Defined to the minor version number of Clang (e.g., the 0 in
 230   2.0.1).</dd>
 231
 232   <dt><code>__clang_patchlevel__</code></dt>
 233   <dd>Defined to the patch level of Clang (e.g., the 1 in 2.0.1).</dd>
 234
 235   <dt><code>__clang_version__</code></dt>
 236   <dd>Defined to a string that captures the Clang version, including
 237   the Subversion tag or revision number, e.g., "1.5 (trunk
 238   102332)".</dd>
 239 </dl>
 240
 241 <!-- ======================================================================= -->
 242 <h2 id="vectors">Vectors and Extended Vectors</h2>
 243 <!-- ======================================================================= -->
 244
 245 <p>Supports the GCC vector extensions, plus some stuff like V[1].</p>
 246
 247 <p>Also supports <tt>ext_vector</tt>, which additionally support for V.xyzw
 248 syntax and other tidbits as seen in OpenCL. An example is:</p>
 249
 250 <blockquote>
 251 <pre>
 252 typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>;
 253 typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>;
 254
 255 float4 foo(float2 a, float2 b) {
 256   float4 c;
 257   c.xz = a;
 258   c.yw = b;
 259   return c;
 260 }
 261 </blockquote>
 262
 263 <p>Query for this feature with __has_feature(attribute_ext_vector_type).</p>
 264
 265 <p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
 266
 267 <!-- ======================================================================= -->
 268 <h2 id="checking_language_features">Checks for Standard Language Features</h2>
 269 <!-- ======================================================================= -->
 270
 271 <p>The <tt>__has_feature</tt> macro can be used to query if certain standard language features are
 272 enabled.  Those features are listed here.</p>
 273
 274 <h3 id="cxx_exceptions">C++ exceptions</h3>
 275
 276 <p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For
 277 example, compiling code with <tt>-fexceptions</tt> enables C++ exceptions.</p>
 278
 279 <h3 id="cxx_rtti">C++ RTTI</h3>
 280
 281 <p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example,
 282 compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p>
 283
 284 <!-- ======================================================================= -->
 285 <h2 id="checking_upcoming_features">Checks for Upcoming Standard Language Features</h2>
 286 <!-- ======================================================================= -->
 287
 288 <p>The <tt>__has_feature</tt> macro can be used to query if certain upcoming
 289 standard language features are enabled.  Those features are listed here.</p>
 290
 291 <p>Currently, all features listed here are slated for inclusion in the upcoming
 292 C++0x standard. As a result, all the features that clang supports are enabled
 293 with the <tt>-std=c++0x</tt> option when compiling C++ code. Features that are
 294 not yet implemented will be noted.</p>
 295
 296 <h3 id="cxx_decltype">C++0x <tt>decltype()</tt></h3>
 297
 298 <p>Use <tt>__has_feature(cxx_decltype)</tt> to determine if support for the
 299 <tt>decltype()</tt> specifier is enabled.</p>
 300
 301 <h3 id="cxx_attributes">C++0x attributes</h3>
 302
 303 <p>Use <tt>__has_feature(cxx_attributes)</tt> to determine if support for
 304 attribute parsing with C++0x's square bracket notation is enabled.
 305
 306 <h3 id="cxx_deleted_functions">C++0x deleted functions</tt></h3>
 307
 308 <p>Use <tt>__has_feature(cxx_deleted_functions)</tt> to determine if support for
 309 deleted function definitions (with <tt>= delete</tt>) is enabled.
 310
 311 <h3 id="cxx_concepts">C++ TR concepts</h3>
 312
 313 <p>Use <tt>__has_feature(cxx_concepts)</tt> to determine if support for
 314 concepts is enabled. clang does not currently implement this feature.
 315
 316 <h3 id="cxx_lambdas">C++0x lambdas</h3>
 317
 318 <p>Use <tt>__has_feature(cxx_lambdas)</tt> to determine if support for
 319 lambdas is enabled. clang does not currently implement this feature.
 320
 321 <h3 id="cxx_nullptr">C++0x <tt>nullptr</tt></h3>
 322
 323 <p>Use <tt>__has_feature(cxx_nullptr)</tt> to determine if support for
 324 <tt>nullptr</tt> is enabled. clang does not yet fully implement this feature.
 325
 326 <h3 id="cxx_rvalue_references">C++0x rvalue references</tt></h3>
 327
 328 <p>Use <tt>__has_feature(cxx_rvalue_references)</tt> to determine if support for
 329 rvalue references is enabled. clang does not yet fully implement this feature.
 330
 331 <h3 id="cxx_static_assert">C++0x <tt>static_assert()</tt></h3>
 332
 333 <p>Use <tt>__has_feature(cxx_static_assert)</tt> to determine if support for
 334 compile-time assertions using <tt>static_assert</tt> is enabled.</p>
 335
 336 <h3 id="cxx_auto_type">C++0x type inference</h3>
 337
 338 <p>Use <tt>__has_feature(cxx_auto_type)</tt> to determine C++0x type inference
 339 is supported using the <tt>auto</tt> specifier. If this is disabled,
 340 <tt>auto</tt> will instead be a storage class specifier, as in C or C++98.</p>
 341
 342 <h3 id="cxx_variadic_templates">C++0x variadic templates</tt></h3>
 343
 344 <p>Use <tt>__has_feature(cxx_variadic_templates)</tt> to determine if support
 345 for templates taking any number of arguments with the ellipsis notation is
 346 enabled. clang does not yet fully implement this feature.</p>
 347
 348 <!-- ======================================================================= -->
 349 <h2 id="blocks">Blocks</h2>
 350 <!-- ======================================================================= -->
 351
 352 <p>The syntax and high level language feature description is in <a
 353 href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>.  Implementation and ABI
 354 details for the clang implementation are in <a
 355 href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p>
 356
 357
 358 <p>Query for this feature with __has_feature(blocks).</p>
 359
 360 <!-- ======================================================================= -->
 361 <h2 id="overloading-in-c">Function Overloading in C</h2>
 362 <!-- ======================================================================= -->
 363
 364 <p>Clang provides support for C++ function overloading in C. Function
 365 overloading in C is introduced using the <tt>overloadable</tt> attribute. For
 366 example, one might provide several overloaded versions of a <tt>tgsin</tt>
 367 function that invokes the appropriate standard function computing the sine of a
 368 value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
 369 precision:</p>
 370
 371 <blockquote>
 372 <pre>
 373 #include &lt;math.h&gt;
 374 float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
 375 double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
 376 long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
 377 </pre>
 378 </blockquote>
 379
 380 <p>Given these declarations, one can call <tt>tgsin</tt> with a
 381 <tt>float</tt> value to receive a <tt>float</tt> result, with a
 382 <tt>double</tt> to receive a <tt>double</tt> result, etc. Function
 383 overloading in C follows the rules of C++ function overloading to pick
 384 the best overload given the call arguments, with a few C-specific
 385 semantics:</p>
 386 <ul>
 387   <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
 388   double</tt> is ranked as a floating-point promotion (per C99) rather
 389   than as a floating-point conversion (as in C++).</li>
 390
 391   <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
 392   <tt>U*</tt> is considered a pointer conversion (with conversion
 393   rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
 394
 395   <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
 396   is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
 397   conversion is given "conversion" rank.</li>
 398 </ul>
 399
 400 <p>The declaration of <tt>overloadable</tt> functions is restricted to
 401 function declarations and definitions. Most importantly, if any
 402 function with a given name is given the <tt>overloadable</tt>
 403 attribute, then all function declarations and definitions with that
 404 name (and in that scope) must have the <tt>overloadable</tt>
 405 attribute. This rule even applies to redeclarations of functions whose original
 406 declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
 407
 408 <blockquote>
 409 <pre>
 410 int f(int) __attribute__((overloadable));
 411 float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
 412
 413 int g(int) __attribute__((overloadable));
 414 int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
 415 </pre>
 416 </blockquote>
 417
 418 <p>Functions marked <tt>overloadable</tt> must have
 419 prototypes. Therefore, the following code is ill-formed:</p>
 420
 421 <blockquote>
 422 <pre>
 423 int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
 424 </pre>
 425 </blockquote>
 426
 427 <p>However, <tt>overloadable</tt> functions are allowed to use a
 428 ellipsis even if there are no named parameters (as is permitted in C++). This feature is particularly useful when combined with the <tt>unavailable</tt> attribute:</p>
 429
 430 <blockquote>
 431 <pre>
 432 void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
 433 </pre>
 434 </blockquote>
 435
 436 <p>Functions declared with the <tt>overloadable</tt> attribute have
 437 their names mangled according to the same rules as C++ function
 438 names. For example, the three <tt>tgsin</tt> functions in our
 439 motivating example get the mangled names <tt>_Z5tgsinf</tt>,
 440 <tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
 441 caveats to this use of name mangling:</p>
 442
 443 <ul>
 444
 445   <li>Future versions of Clang may change the name mangling of
 446   functions overloaded in C, so you should not depend on an specific
 447   mangling. To be completely safe, we strongly urge the use of
 448   <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
 449
 450   <li>The <tt>overloadable</tt> attribute has almost no meaning when
 451   used in C++, because names will already be mangled and functions are
 452   already overloadable. However, when an <tt>overloadable</tt>
 453   function occurs within an <tt>extern "C"</tt> linkage specification,
 454   it's name <i>will</i> be mangled in the same way as it would in
 455   C.</li>
 456 </ul>
 457
 458 <p>Query for this feature with __has_feature(attribute_overloadable).</p>
 459
 460
 461 <!-- ======================================================================= -->
 462 <h2 id="builtins">Builtin Functions</h2>
 463 <!-- ======================================================================= -->
 464
 465 <p>Clang supports a number of builtin library functions with the same syntax as
 466 GCC, including things like <tt>__builtin_nan</tt>,
 467 <tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
 468 <tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc.  In
 469 addition to the GCC builtins, Clang supports a number of builtins that GCC does
 470 not, which are listed here.</p>
 471
 472 <p>Please note that Clang does not and will not support all of the GCC builtins
 473 for vector operations.  Instead of using builtins, you should use the functions
 474 defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
 475 define portable wrappers for these.  Many of the Clang versions of these
 476 functions are implemented directly in terms of <a href="#vectors">extended
 477 vector support</a> instead of builtins, in order to reduce the number of
 478 builtins that we need to implement.</p>
 479
 480 <!-- ======================================================================= -->
 481 <h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
 482 <!-- ======================================================================= -->
 483
 484 <p><tt>__builtin_shufflevector</tt> is used to express generic vector
 485 permutation/shuffle/swizzle operations. This builtin is also very important for
 486 the implementation of various target-specific header files like
 487 <tt>&lt;xmmintrin.h&gt;</tt>.
 488 </p>
 489
 490 <p><b>Syntax:</b></p>
 491
 492 <pre>
 493 __builtin_shufflevector(vec1, vec2, index1, index2, ...)
 494 </pre>
 495
 496 <p><b>Examples:</b></p>
 497
 498 <pre>
 499   // Identity operation - return 4-element vector V1.
 500   __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
 501
 502   // "Splat" element 0 of V1 into a 4-element result.
 503   __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
 504
 505   // Reverse 4-element vector V1.
 506   __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
 507
 508   // Concatenate every other element of 4-element vectors V1 and V2.
 509   __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
 510
 511   // Concatenate every other element of 8-element vectors V1 and V2.
 512   __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
 513 </pre>
 514
 515 <p><b>Description:</b></p>
 516
 517 <p>The first two arguments to __builtin_shufflevector are vectors that have the
 518 same element type.  The remaining arguments are a list of integers that specify
 519 the elements indices of the first two vectors that should be extracted and
 520 returned in a new vector.  These element indices are numbered sequentially
 521 starting with the first vector, continuing into the second vector.  Thus, if
 522 vec1 is a 4-element vector, index 5 would refer to the second element of vec2.
 523 </p>
 524
 525 <p>The result of __builtin_shufflevector is a vector
 526 with the same element type as vec1/vec2 but that has an element count equal to
 527 the number of indices specified.
 528 </p>
 529
 530 <p>Query for this feature with __has_builtin(__builtin_shufflevector).</p>
 531
 532 <!-- ======================================================================= -->
 533 <h3 id="__builtin_unreachable">__builtin_unreachable</h3>
 534 <!-- ======================================================================= -->
 535
 536 <p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in
 537 the program cannot be reached, even if the compiler might otherwise think it
 538 can.  This is useful to improve optimization and eliminates certain warnings.
 539 For example, without the <tt>__builtin_unreachable</tt> in the example below,
 540 the compiler assumes that the inline asm can fall through and prints a "function
 541 declared 'noreturn' should not return" warning.
 542 </p>
 543
 544 <p><b>Syntax:</b></p>
 545
 546 <pre>
 547 __builtin_unreachable()
 548 </pre>
 549
 550 <p><b>Example of Use:</b></p>
 551
 552 <pre>
 553 void myabort(void) __attribute__((noreturn));
 554 void myabort(void) {
 555     asm("int3");
 556     __builtin_unreachable();
 557 }
 558 </pre>
 559
 560 <p><b>Description:</b></p>
 561
 562 <p>The __builtin_unreachable() builtin has completely undefined behavior.  Since
 563 it has undefined behavior, it is a statement that it is never reached and the
 564 optimizer can take advantage of this to produce better code.  This builtin takes
 565 no arguments and produces a void result.
 566 </p>
 567
 568 <p>Query for this feature with __has_builtin(__builtin_unreachable).</p>
 569
 570
 571 <!-- ======================================================================= -->
 572 <h2 id="targetspecific">Target-Specific Extensions</h2>
 573 <!-- ======================================================================= -->
 574
 575 <p>Clang supports some language features conditionally on some targets.</p>
 576
 577 <!-- ======================================================================= -->
 578 <h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
 579 <!-- ======================================================================= -->
 580
 581 <p>The X86 backend has these language extensions:</p>
 582
 583 <!-- ======================================================================= -->
 584 <h4 id="x86-gs-segment">Memory references off the GS segment</h4>
 585 <!-- ======================================================================= -->
 586
 587 <p>Annotating a pointer with address space #256 causes it to  be code generated
 588 relative to the X86 GS segment register, and address space #257 causes it to be
 589 relative to the X86 FS segment.  Note that this is a very very low-level
 590 feature that should only be used if you know what you're doing (for example in
 591 an OS kernel).</p>
 592
 593 <p>Here is an example:</p>
 594
 595 <pre>
 596 #define GS_RELATIVE __attribute__((address_space(256)))
 597 int foo(int GS_RELATIVE *P) {
 598   return *P;
 599 }
 600 </pre>
 601
 602 <p>Which compiles to (on X86-32):</p>
 603
 604 <pre>
 605 _foo:
 606         movl    4(%esp), %eax
 607         movl    %gs:(%eax), %eax
 608         ret
 609 </pre>
 610
 611 <!-- ======================================================================= -->
 612 <h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
 613 <!-- ======================================================================= -->
 614
 615 <p>Clang supports additional attributes that are useful for documenting program
 616 invariants and rules for static analysis tools. The extensions documented here
 617 are used by the <a
 618 href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
 619 engine</a> that is part of Clang's Analysis library.</p>
 620
 621 <!-- ======================================================================= -->
 622 <h3 id="analyzerattributes">Analyzer Attributes</h3>
 623 <!-- ======================================================================= -->
 624
 625 <h4 id="attr_analyzer_noreturn"><tt>analyzer_noreturn</tt></h4>
 626
 627 <p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
 628 attribute. This attribute, which is typically affixed to a function prototype,
 629 indicates that a call to a given function never returns. Function prototypes for
 630 common functions like <tt>exit</tt> are typically annotated with this attribute,
 631 as well as a variety of common assertion handlers. Users can educate the static
 632 analyzer about their own custom assertion handles (thus cutting down on false
 633 positives due to false paths) by marking their own &quot;panic&quot; functions
 634 with this attribute.</p>
 635
 636 <p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
 637 there are special functions that for all intents and purposes should be
 638 considered panic functions (i.e., they are only called when an internal program
 639 error occurs) but may actually return so that the program can fail gracefully.
 640 The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
 641 as being interpreted as &quot;no return&quot; functions by the analyzer (thus
 642 pruning bogus paths) but will not affect compilation (as in the case of
 643 <tt>noreturn</tt>).</p>
 644
 645 <p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the
 646 same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
 647 placed at the end of function prototypes:</p>
 648
 649 <pre>
 650   void foo() <b>__attribute__((analyzer_noreturn))</b>;
 651 </pre>
 652
 653 <p>Query for this feature with __has_feature(attribute_analyzer_noreturn).</p>
 654
 655
 656 </div>
 657 </body>
 658 </html>