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