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