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