granicus.if.org Git - clang/blob - docs/LanguageExtensions.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2           "http://www.w3.org/TR/html4/strict.dtd">
   3 <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
   4 <html>
   5 <head>
   6   <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   7   <title>Clang Language Extensions</title>
   8   <link type="text/css" rel="stylesheet" href="../menu.css">
   9   <link type="text/css" rel="stylesheet" href="../content.css">
  10   <style type="text/css">
  11     td {
  12             vertical-align: top;
  13     }
  14   </style>
  15 </head>
  16 <body>
  17
  18 <!--#include virtual="../menu.html.incl"-->
  19
  20 <div id="content">
  21
  22 <h1>Clang Language Extensions</h1>
  23
  24 <ul>
  25 <li><a href="#intro">Introduction</a></li>
  26 <li><a href="#feature_check">Feature Checking Macros</a></li>
  27 <li><a href="#has_include">Include File Checking Macros</a></li>
  28 <li><a href="#builtinmacros">Builtin Macros</a></li>
  29 <li><a href="#vectors">Vectors and Extended Vectors</a></li>
  30 <li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li>
  31 <li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li>
  32 <li><a href="#checking_language_features">Checks for Standard Language Features</a>
  33   <ul>
  34   <li><a href="#cxx_exceptions">C++ exceptions</a></li>
  35   <li><a href="#cxx_rtti">C++ RTTI</a></li>
  36   </ul></li>
  37 <li><a href="#checking_upcoming_features">Checks for Upcoming Standard Language Features</a>
  38   <ul>
  39   <li><a href="#cxx0x">C++11</a>
  40     <ul>
  41    <li><a href="#cxx_access_control_sfinae">C++11 SFINAE includes
  42    access control</a></li>
  43     <li><a href="#cxx_alias_templates">C++11 alias templates</a></li>
  44     <li><a href="#cxx_alignas">C++11 alignment specifiers</a></li>
  45     <li><a href="#cxx_attributes">C++11 attributes</a></li>
  46     <li><a href="#cxx_constexpr">C++11 generalized constant expressions</a></li>
  47     <li><a href="#cxx_decltype">C++11 <tt>decltype()</tt></a></li>
  48     <li><a href="#cxx_default_function_template_args">C++11 default template arguments in function templates</a></li>
  49     <li><a href="#cxx_defaulted_functions">C++11 defaulted functions</a></li>
  50     <li><a href="#cxx_delegating_constructor">C++11 delegating constructors</a></li>
  51     <li><a href="#cxx_deleted_functions">C++11 deleted functions</a></li>
  52     <li><a href="#cxx_explicit_conversions">C++11 explicit conversion functions</a></li>
  53     <li><a href="#cxx_generalized_initializers">C++11 generalized initializers</a></li>
  54     <li><a href="#cxx_implicit_moves">C++11 implicit move constructors/assignment operators</a></li>
  55     <li><a href="#cxx_inheriting_constructors">C++11 inheriting constructors</a></li>
  56     <li><a href="#cxx_inline_namespaces">C++11 inline namespaces</a></li>
  57     <li><a href="#cxx_lambdas">C++11 lambdas</a></li>
  58     <li><a href="#cxx_noexcept">C++11 noexcept specification</a></li>
  59     <li><a href="#cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</a></li>
  60     <li><a href="#cxx_nullptr">C++11 nullptr</a></li>
  61     <li><a href="#cxx_override_control">C++11 override control</a></li>
  62     <li><a href="#cxx_range_for">C++11 range-based for loop</a></li>
  63     <li><a href="#cxx_raw_string_literals">C++11 raw string literals</a></li>
  64     <li><a href="#cxx_rvalue_references">C++11 rvalue references</a></li>
  65     <li><a href="#cxx_reference_qualified_functions">C++11 reference-qualified functions</a></li>
  66     <li><a href="#cxx_static_assert">C++11 <tt>static_assert()</tt></a></li>
  67     <li><a href="#cxx_auto_type">C++11 type inference</a></li>
  68    <li><a href="#cxx_strong_enums">C++11 strongly-typed enumerations</a></li>
  69     <li><a href="#cxx_trailing_return">C++11 trailing return type</a></li>
  70     <li><a href="#cxx_unicode_literals">C++11 Unicode string literals</a></li>
  71     <li><a href="#cxx_unrestricted_unions">C++11 unrestricted unions</a></li>
  72     <li><a href="#cxx_user_literals">C++11 user-defined literals</a></li>
  73     <li><a href="#cxx_variadic_templates">C++11 variadic templates</a></li>
  74    </ul></li>
  75   <li><a href="#c11">C11</a>
  76     <ul>
  77     <li><a href="#c_alignas">C11 alignment specifiers</a></li>
  78     <li><a href="#c_generic_selections">C11 generic selections</a></li>
  79     <li><a href="#c_static_assert">C11 <tt>_Static_assert()</tt></a></li>
  80     </ul></li>
  81   </ul> </li>
  82 <li><a href="#checking_type_traits">Checks for Type Traits</a></li>
  83 <li><a href="#blocks">Blocks</a></li>
  84 <li><a href="#objc_features">Objective-C Features</a>
  85   <ul>
  86     <li><a href="#objc_instancetype">Related result types</a></li>
  87     <li><a href="#objc_arc">Automatic reference counting</a></li>
  88     <li><a href="#objc_fixed_enum">Enumerations with a fixed underlying type</a></li>
  89   </ul>
  90 </li>
  91 <li><a href="#overloading-in-c">Function Overloading in C</a></li>
  92 <li><a href="#complex-list-init">Initializer lists for complex numbers in C</a></li>
  93 <li><a href="#builtins">Builtin Functions</a>
  94   <ul>
  95   <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
  96   <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li>
  97   <li><a href="#__sync_swap">__sync_swap</a></li>
  98  </ul>
  99 </li>
 100 <li><a href="#targetspecific">Target-Specific Extensions</a>
 101   <ul>
 102   <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li>
 103   </ul>
 104 </li>
 105 <li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li>
 106 <li><a href="#dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</a>
 107   <ul>
 108   <li><a href="#address_sanitizer">AddressSanitizer</a></li>
 109   </ul>
 110 </li>
 111 <li><a href="#threadsafety">Thread Safety Annotation Checking</a>
 112     <ul>
 113     <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li>
 114     <li><a href="#ts_lockable"><tt>lockable</tt></a></li>
 115     <li><a href="#ts_scopedlockable"><tt>scoped_lockable</tt></a></li>
 116     <li><a href="#ts_guardedvar"><tt>guarded_var</tt></a></li>
 117     <li><a href="#ts_ptguardedvar"><tt>pt_guarded_var</tt></a></li>
 118     <li><a href="#ts_guardedby"><tt>guarded_by(l)</tt></a></li>
 119     <li><a href="#ts_ptguardedby"><tt>pt_guarded_by(l)</tt></a></li>
 120     <li><a href="#ts_acquiredbefore"><tt>acquired_before(...)</tt></a></li>
 121     <li><a href="#ts_acquiredafter"><tt>acquired_after(...)</tt></a></li>
 122     <li><a href="#ts_elf"><tt>exclusive_lock_function(...)</tt></a></li>
 123     <li><a href="#ts_slf"><tt>shared_lock_function(...)</tt></a></li>
 124     <li><a href="#ts_etf"><tt>exclusive_trylock_function(...)</tt></a></li>
 125     <li><a href="#ts_stf"><tt>shared_trylock_function(...)</tt></a></li>
 126     <li><a href="#ts_uf"><tt>unlock_function(...)</tt></a></li>
 127     <li><a href="#ts_lr"><tt>lock_returned(l)</tt></a></li>
 128     <li><a href="#ts_le"><tt>locks_excluded(...)</tt></a></li>
 129     <li><a href="#ts_elr"><tt>exclusive_locks_required(...)</tt></a></li>
 130     <li><a href="#ts_slr"><tt>shared_locks_required(...)</tt></a></li>
 131     </ul>
 132 </li>
 133 </ul>
 134
 135 <!-- ======================================================================= -->
 136 <h2 id="intro">Introduction</h2>
 137 <!-- ======================================================================= -->
 138
 139 <p>This document describes the language extensions provided by Clang.  In
 140 addition to the language extensions listed here, Clang aims to support a broad
 141 range of GCC extensions.  Please see the <a
 142 href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
 143 more information on these extensions.</p>
 144
 145 <!-- ======================================================================= -->
 146 <h2 id="feature_check">Feature Checking Macros</h2>
 147 <!-- ======================================================================= -->
 148
 149 <p>Language extensions can be very useful, but only if you know you can depend
 150 on them.  In order to allow fine-grain features checks, we support three builtin
 151 function-like macros.  This allows you to directly test for a feature in your
 152 code without having to resort to something like autoconf or fragile "compiler
 153 version checks".</p>
 154
 155 <!-- ======================================================================= -->
 156 <h3><a name="__has_builtin">__has_builtin</a></h3>
 157 <!-- ======================================================================= -->
 158
 159 <p>This function-like macro takes a single identifier argument that is the name
 160 of a builtin function.  It evaluates to 1 if the builtin is supported or 0 if
 161 not.  It can be used like this:</p>
 162
 163 <blockquote>
 164 <pre>
 165 #ifndef __has_builtin         // Optional of course.
 166   #define __has_builtin(x) 0  // Compatibility with non-clang compilers.
 167 #endif
 168
 169 ...
 170 #if __has_builtin(__builtin_trap)
 171   __builtin_trap();
 172 #else
 173   abort();
 174 #endif
 175 ...
 176 </pre>
 177 </blockquote>
 178
 179
 180 <!-- ======================================================================= -->
 181 <h3><a name="__has_feature_extension"> __has_feature and __has_extension</a></h3>
 182 <!-- ======================================================================= -->
 183
 184 <p>These function-like macros take a single identifier argument that is the
 185 name of a feature.  <code>__has_feature</code> evaluates to 1 if the feature
 186 is both supported by Clang and standardized in the current language standard
 187 or 0 if not (but see <a href="#has_feature_back_compat">below</a>), while
 188 <code>__has_extension</code> evaluates to 1 if the feature is supported by
 189 Clang in the current language (either as a language extension or a standard
 190 language feature) or 0 if not.  They can be used like this:</p>
 191
 192 <blockquote>
 193 <pre>
 194 #ifndef __has_feature         // Optional of course.
 195   #define __has_feature(x) 0  // Compatibility with non-clang compilers.
 196 #endif
 197 #ifndef __has_extension
 198   #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
 199 #endif
 200
 201 ...
 202 #if __has_feature(cxx_rvalue_references)
 203 // This code will only be compiled with the -std=c++11 and -std=gnu++11
 204 // options, because rvalue references are only standardized in C++11.
 205 #endif
 206
 207 #if __has_extension(cxx_rvalue_references)
 208 // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98
 209 // and -std=gnu++98 options, because rvalue references are supported as a
 210 // language extension in C++98.
 211 #endif
 212 </pre>
 213 </blockquote>
 214
 215 <p id="has_feature_back_compat">For backwards compatibility reasons,
 216 <code>__has_feature</code> can also be used to test for support for
 217 non-standardized features, i.e. features not prefixed <code>c_</code>,
 218 <code>cxx_</code> or <code>objc_</code>.</p>
 219
 220 <p id="has_feature_for_non_language_features">
 221 Another use of <code>__has_feature</code> is to check for compiler features
 222 not related to the language standard, such as e.g.
 223 <a href="AddressSanitizer.html">AddressSanitizer</a>.
 224
 225 <p>If the <code>-pedantic-errors</code> option is given,
 226 <code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p>
 227
 228 <p>The feature tag is described along with the language feature below.</p>
 229
 230 <!-- ======================================================================= -->
 231 <h3><a name="__has_attribute">__has_attribute</a></h3>
 232 <!-- ======================================================================= -->
 233
 234 <p>This function-like macro takes a single identifier argument that is the name
 235 of an attribute.  It evaluates to 1 if the attribute is supported or 0 if not.  It
 236 can be used like this:</p>
 237
 238 <blockquote>
 239 <pre>
 240 #ifndef __has_attribute         // Optional of course.
 241   #define __has_attribute(x) 0  // Compatibility with non-clang compilers.
 242 #endif
 243
 244 ...
 245 #if __has_attribute(always_inline)
 246 #define ALWAYS_INLINE __attribute__((always_inline))
 247 #else
 248 #define ALWAYS_INLINE
 249 #endif
 250 ...
 251 </pre>
 252 </blockquote>
 253
 254 <!-- ======================================================================= -->
 255 <h2 id="has_include">Include File Checking Macros</h2>
 256 <!-- ======================================================================= -->
 257
 258 <p>Not all developments systems have the same include files.
 259 The <a href="#__has_include">__has_include</a> and
 260 <a href="#__has_include_next">__has_include_next</a> macros allow you to
 261 check for the existence of an include file before doing
 262 a possibly failing #include directive.</p>
 263
 264 <!-- ======================================================================= -->
 265 <h3><a name="__has_include">__has_include</a></h3>
 266 <!-- ======================================================================= -->
 267
 268 <p>This function-like macro takes a single file name string argument that
 269 is the name of an include file.  It evaluates to 1 if the file can
 270 be found using the include paths, or 0 otherwise:</p>
 271
 272 <blockquote>
 273 <pre>
 274 // Note the two possible file name string formats.
 275 #if __has_include("myinclude.h") &amp;&amp; __has_include(&lt;stdint.h&gt;)
 276 # include "myinclude.h"
 277 #endif
 278
 279 // To avoid problem with non-clang compilers not having this macro.
 280 #if defined(__has_include) &amp;&amp; __has_include("myinclude.h")
 281 # include "myinclude.h"
 282 #endif
 283 </pre>
 284 </blockquote>
 285
 286 <p>To test for this feature, use #if defined(__has_include).</p>
 287
 288 <!-- ======================================================================= -->
 289 <h3><a name="__has_include_next">__has_include_next</a></h3>
 290 <!-- ======================================================================= -->
 291
 292 <p>This function-like macro takes a single file name string argument that
 293 is the name of an include file.  It is like __has_include except that it
 294 looks for the second instance of the given file found in the include
 295 paths.  It evaluates to 1 if the second instance of the file can
 296 be found using the include paths, or 0 otherwise:</p>
 297
 298 <blockquote>
 299 <pre>
 300 // Note the two possible file name string formats.
 301 #if __has_include_next("myinclude.h") &amp;&amp; __has_include_next(&lt;stdint.h&gt;)
 302 # include_next "myinclude.h"
 303 #endif
 304
 305 // To avoid problem with non-clang compilers not having this macro.
 306 #if defined(__has_include_next) &amp;&amp; __has_include_next("myinclude.h")
 307 # include_next "myinclude.h"
 308 #endif
 309 </pre>
 310 </blockquote>
 311
 312 <p>Note that __has_include_next, like the GNU extension
 313 #include_next directive, is intended for use in headers only,
 314 and will issue a warning if used in the top-level compilation
 315 file.  A warning will also be issued if an absolute path
 316 is used in the file argument.</p>
 317
 318
 319 <!-- ======================================================================= -->
 320 <h3><a name="__has_warning">__has_warning</a></h3>
 321 <!-- ======================================================================= -->
 322
 323 <p>This function-like macro takes a string literal that represents a command
 324   line option for a warning and returns true if that is a valid warning
 325   option.</p>
 326
 327 <blockquote>
 328 <pre>
 329 #if __has_warning("-Wformat")
 330 ...
 331 #endif
 332 </pre>
 333 </blockquote>
 334
 335 <!-- ======================================================================= -->
 336 <h2 id="builtinmacros">Builtin Macros</h2>
 337 <!-- ======================================================================= -->
 338
 339 <dl>
 340   <dt><code>__BASE_FILE__</code></dt>
 341   <dd>Defined to a string that contains the name of the main input
 342   file passed to Clang.</dd>
 343
 344   <dt><code>__COUNTER__</code></dt>
 345   <dd>Defined to an integer value that starts at zero and is
 346   incremented each time the <code>__COUNTER__</code> macro is
 347   expanded.</dd>
 348
 349   <dt><code>__INCLUDE_LEVEL__</code></dt>
 350   <dd>Defined to an integral value that is the include depth of the
 351   file currently being translated. For the main file, this value is
 352   zero.</dd>
 353
 354   <dt><code>__TIMESTAMP__</code></dt>
 355   <dd>Defined to the date and time of the last modification of the
 356   current source file.</dd>
 357
 358   <dt><code>__clang__</code></dt>
 359   <dd>Defined when compiling with Clang</dd>
 360
 361   <dt><code>__clang_major__</code></dt>
 362   <dd>Defined to the major marketing version number of Clang (e.g., the
 363   2 in 2.0.1).  Note that marketing version numbers should not be used to
 364   check for language features, as different vendors use different numbering
 365   schemes.  Instead, use the <a href="#feature_check">feature checking
 366   macros</a>.</dd>
 367
 368   <dt><code>__clang_minor__</code></dt>
 369   <dd>Defined to the minor version number of Clang (e.g., the 0 in
 370   2.0.1).  Note that marketing version numbers should not be used to
 371   check for language features, as different vendors use different numbering
 372   schemes.  Instead, use the <a href="#feature_check">feature checking
 373   macros</a>.</dd>
 374
 375   <dt><code>__clang_patchlevel__</code></dt>
 376   <dd>Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).</dd>
 377
 378   <dt><code>__clang_version__</code></dt>
 379   <dd>Defined to a string that captures the Clang marketing version, including
 380   the Subversion tag or revision number, e.g., "1.5 (trunk 102332)".</dd>
 381 </dl>
 382
 383 <!-- ======================================================================= -->
 384 <h2 id="vectors">Vectors and Extended Vectors</h2>
 385 <!-- ======================================================================= -->
 386
 387 <p>Supports the GCC vector extensions, plus some stuff like V[1].</p>
 388
 389 <p>Also supports <tt>ext_vector</tt>, which additionally support for V.xyzw
 390 syntax and other tidbits as seen in OpenCL. An example is:</p>
 391
 392 <blockquote>
 393 <pre>
 394 typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>;
 395 typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>;
 396
 397 float4 foo(float2 a, float2 b) {
 398   float4 c;
 399   c.xz = a;
 400   c.yw = b;
 401   return c;
 402 }
 403 </pre>
 404 </blockquote>
 405
 406 <p>Query for this feature with __has_extension(attribute_ext_vector_type).</p>
 407
 408 <p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
 409
 410 <!-- ======================================================================= -->
 411 <h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2>
 412 <!-- ======================================================================= -->
 413
 414 <p>An optional string message can be added to the <tt>deprecated</tt>
 415 and <tt>unavailable</tt> attributes.  For example:</p>
 416
 417 <blockquote>
 418 <pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre>
 419 </blockquote>
 420
 421 <p>If the deprecated or unavailable declaration is used, the message
 422 will be incorporated into the appropriate diagnostic:</p>
 423
 424 <blockquote>
 425 <pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! [-Wdeprecated-declarations]
 426   explode();
 427   ^</pre>
 428 </blockquote>
 429
 430 <p>Query for this feature
 431 with <tt>__has_extension(attribute_deprecated_with_message)</tt>
 432 and <tt>__has_extension(attribute_unavailable_with_message)</tt>.</p>
 433
 434 <!-- ======================================================================= -->
 435 <h2 id="attributes-on-enumerators">Attributes on Enumerators</h2>
 436 <!-- ======================================================================= -->
 437
 438 <p>Clang allows attributes to be written on individual enumerators.
 439 This allows enumerators to be deprecated, made unavailable, etc.  The
 440 attribute must appear after the enumerator name and before any
 441 initializer, like so:</p>
 442
 443 <blockquote>
 444 <pre>enum OperationMode {
 445   OM_Invalid,
 446   OM_Normal,
 447   OM_Terrified __attribute__((deprecated)),
 448   OM_AbortOnError __attribute__((deprecated)) = 4
 449 };</pre>
 450 </blockquote>
 451
 452 <p>Attributes on the <tt>enum</tt> declaration do not apply to
 453 individual enumerators.</p>
 454
 455 <p>Query for this feature with <tt>__has_extension(enumerator_attributes)</tt>.</p>
 456
 457 <!-- ======================================================================= -->
 458 <h2 id="checking_language_features">Checks for Standard Language Features</h2>
 459 <!-- ======================================================================= -->
 460
 461 <p>The <tt>__has_feature</tt> macro can be used to query if certain standard language features are
 462 enabled.  Those features are listed here.</p>
 463
 464 <h3 id="cxx_exceptions">C++ exceptions</h3>
 465
 466 <p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For
 467 example, compiling code with <tt>-fexceptions</tt> enables C++ exceptions.</p>
 468
 469 <h3 id="cxx_rtti">C++ RTTI</h3>
 470
 471 <p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example,
 472 compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p>
 473
 474 <!-- ======================================================================= -->
 475 <h2 id="checking_upcoming_features">Checks for Upcoming Standard Language Features</h2>
 476 <!-- ======================================================================= -->
 477
 478 <p>The <tt>__has_feature</tt> or <tt>__has_extension</tt> macros can be used
 479 to query if certain upcoming standard language features are enabled.  Those
 480 features are listed here.  Features that are not yet implemented will be
 481 noted.</p>
 482
 483 <h3 id="cxx0x">C++11</h3>
 484
 485 <p>The features listed below are slated for inclusion in the upcoming
 486 C++11 standard. As a result, all these features are enabled
 487 with the <tt>-std=c++11</tt> option when compiling C++ code.</p>
 488
 489 <h4 id="cxx_access_control_sfinae">C++11 SFINAE includes access control</h4>
 490
 491 <p>Use <tt>__has_feature(cxx_access_control_sfinae)</tt> or <tt>__has_extension(cxx_access_control_sfinae)</tt> to determine whether access-control errors (e.g., calling a private constructor) are considered to be template argument deduction errors (aka SFINAE errors), per <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170">C++ DR1170</a>.</p>
 492
 493 <h4 id="cxx_alias_templates">C++11 alias templates</h4>
 494
 495 <p>Use <tt>__has_feature(cxx_alias_templates)</tt> or
 496 <tt>__has_extension(cxx_alias_templates)</tt> to determine if support for
 497 C++11's alias declarations and alias templates is enabled.</p>
 498
 499 <h4 id="cxx_alignas">C++11 alignment specifiers</h4>
 500
 501 <p>Use <tt>__has_feature(cxx_alignas)</tt> or
 502 <tt>__has_extension(cxx_alignas)</tt> to determine if support for alignment
 503 specifiers using <tt>alignas</tt> is enabled.</p>
 504
 505 <h4 id="cxx_attributes">C++11 attributes</h4>
 506
 507 <p>Use <tt>__has_feature(cxx_attributes)</tt> or
 508 <tt>__has_extension(cxx_attributes)</tt> to determine if support for attribute
 509 parsing with C++11's square bracket notation is enabled.</p>
 510
 511 <h4 id="cxx_constexpr">C++11 generalized constant expressions</h4>
 512
 513 <p>Use <tt>__has_feature(cxx_constexpr)</tt> to determine if support
 514 for generalized constant expressions (e.g., <tt>constexpr</tt>) is
 515 enabled. Clang does not currently implement this feature.</p>
 516
 517 <h4 id="cxx_decltype">C++11 <tt>decltype()</tt></h4>
 518
 519 <p>Use <tt>__has_feature(cxx_decltype)</tt> or
 520 <tt>__has_extension(cxx_decltype)</tt> to determine if support for the
 521 <tt>decltype()</tt> specifier is enabled.</p>
 522
 523 <h4 id="cxx_default_function_template_args">C++11 default template arguments in function templates</h4>
 524
 525 <p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or
 526 <tt>__has_extension(cxx_default_function_template_args)</tt> to determine
 527 if support for default template arguments in function templates is enabled.</p>
 528
 529 <h4 id="cxx_defaulted_functions">C++11 <tt>default</tt>ed functions</h4>
 530
 531 <p>Use <tt>__has_feature(cxx_defaulted_functions)</tt> or
 532 <tt>__has_extension(cxx_defaulted_functions)</tt> to determine if support for
 533 defaulted function definitions (with <tt>= default</tt>) is enabled.</p>
 534
 535 <h4 id="cxx_delegating_constructors">C++11 delegating constructors</h4>
 536
 537 <p>Use <tt>__has_feature(cxx_delegating_constructors)</tt> to determine if
 538 support for delegating constructors is enabled.</p>
 539
 540 <h4 id="cxx_deleted_functions">C++11 <tt>delete</tt>d functions</h4>
 541
 542 <p>Use <tt>__has_feature(cxx_deleted_functions)</tt> or
 543 <tt>__has_extension(cxx_deleted_functions)</tt> to determine if support for
 544 deleted function definitions (with <tt>= delete</tt>) is enabled.</p>
 545
 546 <h4 id="cxx_explicit_conversions">C++11 explicit conversion functions</h4>
 547 <p>Use <tt>__has_feature(cxx_explicit_conversions)</tt> to determine if support for <tt>explicit</tt> conversion functions is enabled.</p>
 548
 549 <h4 id="cxx_generalized_initializers">C++11 generalized initializers</h4>
 550
 551 <p>Use <tt>__has_feature(cxx_generalized_initializers)</tt> to determine if
 552 support for generalized initializers (using braced lists and
 553 <tt>std::initializer_list</tt>) is enabled. Clang does not currently implement
 554 this feature.</p>
 555
 556 <h4 id="cxx_implicit_moves">C++11 implicit move constructors/assignment operators</h4>
 557
 558 <p>Use <tt>__has_feature(cxx_implicit_moves)</tt> to determine if Clang will
 559 implicitly generate move constructors and move assignment operators where needed.</p>
 560
 561 <h4 id="cxx_inheriting_constructors">C++11 inheriting constructors</h4>
 562
 563 <p>Use <tt>__has_feature(cxx_inheriting_constructors)</tt> to determine if support for inheriting constructors is enabled. Clang does not currently implement this feature.</p>
 564
 565 <h4 id="cxx_inline_namespaces">C++11 inline namespaces</h4>
 566
 567 <p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> or
 568 <tt>__has_extension(cxx_inline_namespaces)</tt> to determine if support for
 569 inline namespaces is enabled.</p>
 570
 571 <h4 id="cxx_lambdas">C++11 lambdas</h4>
 572
 573 <p>Use <tt>__has_feature(cxx_lambdas)</tt> or
 574 <tt>__has_extension(cxx_lambdas)</tt> to determine if support for lambdas
 575 is enabled. Clang does not currently implement this feature.</p>
 576
 577 <h4 id="cxx_noexcept">C++11 noexcept</h4>
 578
 579 <p>Use <tt>__has_feature(cxx_noexcept)</tt> or
 580 <tt>__has_extension(cxx_noexcept)</tt> to determine if support for noexcept
 581 exception specifications is enabled.</p>
 582
 583 <h4 id="cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</h4>
 584
 585 <p>Use <tt>__has_feature(cxx_nonstatic_member_init)</tt> to determine whether in-class initialization of non-static data members is enabled.</p>
 586
 587 <h4 id="cxx_nullptr">C++11 <tt>nullptr</tt></h4>
 588
 589 <p>Use <tt>__has_feature(cxx_nullptr)</tt> or
 590 <tt>__has_extension(cxx_nullptr)</tt> to determine if support for
 591 <tt>nullptr</tt> is enabled.</p>
 592
 593 <h4 id="cxx_override_control">C++11 <tt>override control</tt></h4>
 594
 595 <p>Use <tt>__has_feature(cxx_override_control)</tt> or
 596 <tt>__has_extension(cxx_override_control)</tt> to determine if support for
 597 the override control keywords is enabled.</p>
 598
 599 <h4 id="cxx_reference_qualified_functions">C++11 reference-qualified functions</h4>
 600 <p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> or
 601 <tt>__has_extension(cxx_reference_qualified_functions)</tt> to determine
 602 if support for reference-qualified functions (e.g., member functions with
 603 <code>&amp;</code> or <code>&amp;&amp;</code> applied to <code>*this</code>)
 604 is enabled.</p>
 605
 606 <h4 id="cxx_range_for">C++11 range-based <tt>for</tt> loop</h4>
 607
 608 <p>Use <tt>__has_feature(cxx_range_for)</tt> or
 609 <tt>__has_extension(cxx_range_for)</tt> to determine if support for the
 610 range-based for loop is enabled. </p>
 611
 612 <h4 id="cxx_raw_string_literals">C++11 raw string literals</h4>
 613 <p>Use <tt>__has_feature(cxx_raw_string_literals)</tt> to determine if support for raw string literals (e.g., <tt>R"foo\bar"</tt>) is enabled.</p>
 614
 615 <h4 id="cxx_rvalue_references">C++11 rvalue references</h4>
 616
 617 <p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or
 618 <tt>__has_extension(cxx_rvalue_references)</tt> to determine if support for
 619 rvalue references is enabled. </p>
 620
 621 <h4 id="cxx_static_assert">C++11 <tt>static_assert()</tt></h4>
 622
 623 <p>Use <tt>__has_feature(cxx_static_assert)</tt> or
 624 <tt>__has_extension(cxx_static_assert)</tt> to determine if support for
 625 compile-time assertions using <tt>static_assert</tt> is enabled.</p>
 626
 627 <h4 id="cxx_auto_type">C++11 type inference</h4>
 628
 629 <p>Use <tt>__has_feature(cxx_auto_type)</tt> or
 630 <tt>__has_extension(cxx_auto_type)</tt> to determine C++11 type inference is
 631 supported using the <tt>auto</tt> specifier. If this is disabled, <tt>auto</tt>
 632 will instead be a storage class specifier, as in C or C++98.</p>
 633
 634 <h4 id="cxx_strong_enums">C++11 strongly typed enumerations</h4>
 635
 636 <p>Use <tt>__has_feature(cxx_strong_enums)</tt> or
 637 <tt>__has_extension(cxx_strong_enums)</tt> to determine if support for
 638 strongly typed, scoped enumerations is enabled.</p>
 639
 640 <h4 id="cxx_trailing_return">C++11 trailing return type</h4>
 641
 642 <p>Use <tt>__has_feature(cxx_trailing_return)</tt> or
 643 <tt>__has_extension(cxx_trailing_return)</tt> to determine if support for the
 644 alternate function declaration syntax with trailing return type is enabled.</p>
 645
 646 <h4 id="cxx_unicode_literals">C++11 Unicode string literals</h4>
 647 <p>Use <tt>__has_feature(cxx_unicode_literals)</tt> to determine if
 648 support for Unicode string literals is enabled.</p>
 649
 650 <h4 id="cxx_unrestricted_unions">C++11 unrestricted unions</h4>
 651
 652 <p>Use <tt>__has_feature(cxx_unrestricted_unions)</tt> to determine if support for unrestricted unions is enabled. Clang does not currently support this feature.</p>
 653
 654 <h4 id="cxx_user_literals">C++11 user-defined literals</h4>
 655
 656 <p>Use <tt>__has_feature(cxx_user_literals)</tt> to determine if support for user-defined literals is enabled. Clang does not currently support this feature.</p>
 657
 658 <h4 id="cxx_variadic_templates">C++11 variadic templates</h4>
 659
 660 <p>Use <tt>__has_feature(cxx_variadic_templates)</tt> or
 661 <tt>__has_extension(cxx_variadic_templates)</tt> to determine if support
 662 for variadic templates is enabled.</p>
 663
 664 <h3 id="c11">C11</h3>
 665
 666 <p>The features listed below are slated for inclusion in the upcoming
 667 C11 standard. As a result, all these features are enabled
 668 with the <tt>-std=c11</tt> option when compiling C code.</p>
 669
 670 <h4 id="c_alignas">C11 alignment specifiers</h4>
 671
 672 <p>Use <tt>__has_feature(c_alignas)</tt> or <tt>__has_extension(c_alignas)</tt>
 673 to determine if support for alignment specifiers using <tt>_Alignas</tt>
 674 is enabled.</p>
 675
 676 <h4 id="c_generic_selections">C11 generic selections</h4>
 677
 678 <p>Use <tt>__has_feature(c_generic_selections)</tt> or
 679 <tt>__has_extension(c_generic_selections)</tt> to determine if support for
 680 generic selections is enabled.</p>
 681
 682 <p>As an extension, the C11 generic selection expression is available in all
 683 languages supported by Clang.  The syntax is the same as that given in the
 684 C11 standard.</p>
 685
 686 <p>In C, type compatibility is decided according to the rules given in the
 687 appropriate standard, but in C++, which lacks the type compatibility rules
 688 used in C, types are considered compatible only if they are equivalent.</p>
 689
 690 <h4 id="c_static_assert">C11 <tt>_Static_assert()</tt></h4>
 691
 692 <p>Use <tt>__has_feature(c_static_assert)</tt> or
 693 <tt>__has_extension(c_static_assert)</tt> to determine if support for
 694 compile-time assertions using <tt>_Static_assert</tt> is enabled.</p>
 695
 696 <!-- ======================================================================= -->
 697 <h2 id="checking_type_traits">Checks for Type Traits</h2>
 698 <!-- ======================================================================= -->
 699
 700 <p>Clang supports the <a href="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_extension(X)</code> indicates the presence of the type trait. For example:
 701 <blockquote>
 702 <pre>
 703 #if __has_extension(is_convertible_to)
 704 template&lt;typename From, typename To&gt;
 705 struct is_convertible_to {
 706   static const bool value = __is_convertible_to(From, To);
 707 };
 708 #else
 709 // Emulate type trait
 710 #endif
 711 </pre>
 712 </blockquote>
 713
 714 <p>The following type traits are supported by Clang:</p>
 715 <ul>
 716   <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li>
 717   <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li>
 718   <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li>
 719   <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li>
 720   <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li>
 721   <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li>
 722   <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li>
 723   <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li>
 724   <li><code>__is_abstract</code> (GNU, Microsoft)</li>
 725   <li><code>__is_base_of</code> (GNU, Microsoft)</li>
 726   <li><code>__is_class</code> (GNU, Microsoft)</li>
 727   <li><code>__is_convertible_to</code> (Microsoft)</li>
 728   <li><code>__is_empty</code> (GNU, Microsoft)</li>
 729   <li><code>__is_enum</code> (GNU, Microsoft)</li>
 730   <li><code>__is_pod</code> (GNU, Microsoft)</li>
 731   <li><code>__is_polymorphic</code> (GNU, Microsoft)</li>
 732   <li><code>__is_union</code> (GNU, Microsoft)</li>
 733   <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li>
 734   <li><code>__is_final</code>: Determines whether the given type is declared with a <code>final</code> class-virt-specifier.</li>
 735   <li><code>__underlying_type(type)</code>: Retrieves the underlying type for a given <code>enum</code> type. This trait is required to implement the C++11 standard library.</li>
 736 </ul>
 737
 738 <!-- ======================================================================= -->
 739 <h2 id="blocks">Blocks</h2>
 740 <!-- ======================================================================= -->
 741
 742 <p>The syntax and high level language feature description is in <a
 743 href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>.  Implementation and ABI
 744 details for the clang implementation are in <a
 745 href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p>
 746
 747
 748 <p>Query for this feature with __has_extension(blocks).</p>
 749
 750 <!-- ======================================================================= -->
 751 <h2 id="objc_features">Objective-C Features</h2>
 752 <!-- ======================================================================= -->
 753
 754 <h3 id="objc_instancetype">Related result types</h3>
 755
 756 <p>According to Cocoa conventions, Objective-C methods with certain names ("init", "alloc", etc.) always return objects that are an instance of the receiving class's type. Such methods are said to have a "related result type", meaning that a message send to one of these methods will have the same static type as an instance of the receiver class. For example, given the following classes:</p>
 757
 758 <blockquote>
 759 <pre>
 760 @interface NSObject
 761 + (id)alloc;
 762 - (id)init;
 763 @end
 764
 765 @interface NSArray : NSObject
 766 @end
 767 </pre>
 768 </blockquote>
 769
 770 <p>and this common initialization pattern</p>
 771
 772 <blockquote>
 773 <pre>
 774 NSArray *array = [[NSArray alloc] init];
 775 </pre>
 776 </blockquote>
 777
 778 <p>the type of the expression <code>[NSArray alloc]</code> is
 779 <code>NSArray*</code> because <code>alloc</code> implicitly has a
 780 related result type. Similarly, the type of the expression
 781 <code>[[NSArray alloc] init]</code> is <code>NSArray*</code>, since
 782 <code>init</code> has a related result type and its receiver is known
 783 to have the type <code>NSArray *</code>. If neither <code>alloc</code> nor <code>init</code> had a related result type, the expressions would have had type <code>id</code>, as declared in the method signature.</p>
 784
 785 <p>A method with a related result type can be declared by using the
 786 type <tt>instancetype</tt> as its result type. <tt>instancetype</tt>
 787 is a contextual keyword that is only permitted in the result type of
 788 an Objective-C method, e.g.</p>
 789
 790 <pre>
 791 @interface A
 792 + (<b>instancetype</b>)constructAnA;
 793 @end
 794 </pre>
 795
 796 <p>The related result type can also be inferred for some methods.
 797 To determine whether a method has an inferred related result type, the first
 798 word in the camel-case selector (e.g., "init" in "initWithObjects") is
 799 considered, and the method will have a related result type if its return
 800 type is compatible with the type of its class and if</p>
 801
 802 <ul>
 803
 804   <li>the first word is "alloc" or "new", and the method is a class
 805   method, or</li>
 806
 807   <li>the first word is "autorelease", "init", "retain", or "self",
 808   and the method is an instance method.</li>
 809
 810 </ul>
 811
 812 <p>If a method with a related result type is overridden by a subclass
 813 method, the subclass method must also return a type that is compatible
 814 with the subclass type. For example:</p>
 815
 816 <blockquote>
 817 <pre>
 818 @interface NSString : NSObject
 819 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
 820 @end
 821 </pre>
 822 </blockquote>
 823
 824 <p>Related result types only affect the type of a message send or
 825 property access via the given method. In all other respects, a method
 826 with a related result type is treated the same way as method that
 827 returns <tt>id</tt>.</p>
 828
 829 <p>Use <tt>__has_feature(objc_instancetype)</tt> to determine whether
 830 the <tt>instancetype</tt> contextual keyword is available.</p>
 831
 832 <!-- ======================================================================= -->
 833 <h2 id="objc_arc">Automatic reference counting </h2>
 834 <!-- ======================================================================= -->
 835
 836 <p>Clang provides support for <a href="AutomaticReferenceCounting.html">automated reference counting</a> in Objective-C, which eliminates the need for manual retain/release/autorelease message sends. There are two feature macros associated with automatic reference counting: <code>__has_feature(objc_arc)</code> indicates the availability of automated reference counting in general, while <code>__has_feature(objc_arc_weak)</code> indicates that automated reference counting also includes support for <code>__weak</code> pointers to Objective-C objects.</p>
 837
 838 <!-- ======================================================================= -->
 839 <h2 id="objc_fixed_enum">Enumerations with a fixed underlying type</h2>
 840 <!-- ======================================================================= -->
 841
 842 <p>Clang provides support for C++11 enumerations with a fixed
 843 underlying type within Objective-C. For example, one can write an
 844 enumeration type as:</p>
 845
 846 <pre>
 847 typedef enum : unsigned char { Red, Green, Blue } Color;
 848 </pre>
 849
 850 <p>This specifies that the underlying type, which is used to store the
 851 enumeration value, is <tt>unsigned char</tt>.</p>
 852
 853 <p>Use <tt>__has_feature(objc_fixed_enum)</tt> to determine whether
 854 support for fixed underlying types is available in Objective-C.</p>
 855
 856 <!-- ======================================================================= -->
 857 <h2 id="overloading-in-c">Function Overloading in C</h2>
 858 <!-- ======================================================================= -->
 859
 860 <p>Clang provides support for C++ function overloading in C. Function
 861 overloading in C is introduced using the <tt>overloadable</tt> attribute. For
 862 example, one might provide several overloaded versions of a <tt>tgsin</tt>
 863 function that invokes the appropriate standard function computing the sine of a
 864 value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
 865 precision:</p>
 866
 867 <blockquote>
 868 <pre>
 869 #include &lt;math.h&gt;
 870 float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
 871 double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
 872 long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
 873 </pre>
 874 </blockquote>
 875
 876 <p>Given these declarations, one can call <tt>tgsin</tt> with a
 877 <tt>float</tt> value to receive a <tt>float</tt> result, with a
 878 <tt>double</tt> to receive a <tt>double</tt> result, etc. Function
 879 overloading in C follows the rules of C++ function overloading to pick
 880 the best overload given the call arguments, with a few C-specific
 881 semantics:</p>
 882 <ul>
 883   <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
 884   double</tt> is ranked as a floating-point promotion (per C99) rather
 885   than as a floating-point conversion (as in C++).</li>
 886
 887   <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
 888   <tt>U*</tt> is considered a pointer conversion (with conversion
 889   rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
 890
 891   <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
 892   is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
 893   conversion is given "conversion" rank.</li>
 894 </ul>
 895
 896 <p>The declaration of <tt>overloadable</tt> functions is restricted to
 897 function declarations and definitions. Most importantly, if any
 898 function with a given name is given the <tt>overloadable</tt>
 899 attribute, then all function declarations and definitions with that
 900 name (and in that scope) must have the <tt>overloadable</tt>
 901 attribute. This rule even applies to redeclarations of functions whose original
 902 declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
 903
 904 <blockquote>
 905 <pre>
 906 int f(int) __attribute__((overloadable));
 907 float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
 908
 909 int g(int) __attribute__((overloadable));
 910 int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
 911 </pre>
 912 </blockquote>
 913
 914 <p>Functions marked <tt>overloadable</tt> must have
 915 prototypes. Therefore, the following code is ill-formed:</p>
 916
 917 <blockquote>
 918 <pre>
 919 int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
 920 </pre>
 921 </blockquote>
 922
 923 <p>However, <tt>overloadable</tt> functions are allowed to use a
 924 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>
 925
 926 <blockquote>
 927 <pre>
 928 void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
 929 </pre>
 930 </blockquote>
 931
 932 <p>Functions declared with the <tt>overloadable</tt> attribute have
 933 their names mangled according to the same rules as C++ function
 934 names. For example, the three <tt>tgsin</tt> functions in our
 935 motivating example get the mangled names <tt>_Z5tgsinf</tt>,
 936 <tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two
 937 caveats to this use of name mangling:</p>
 938
 939 <ul>
 940
 941   <li>Future versions of Clang may change the name mangling of
 942   functions overloaded in C, so you should not depend on an specific
 943   mangling. To be completely safe, we strongly urge the use of
 944   <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
 945
 946   <li>The <tt>overloadable</tt> attribute has almost no meaning when
 947   used in C++, because names will already be mangled and functions are
 948   already overloadable. However, when an <tt>overloadable</tt>
 949   function occurs within an <tt>extern "C"</tt> linkage specification,
 950   it's name <i>will</i> be mangled in the same way as it would in
 951   C.</li>
 952 </ul>
 953
 954 <p>Query for this feature with __has_extension(attribute_overloadable).</p>
 955
 956 <!-- ======================================================================= -->
 957 <h2 id="complex-list-init">Initializer lists for complex numbers in C</h2>
 958 <!-- ======================================================================= -->
 959
 960 <p>clang supports an extension which allows the following in C:</p>
 961
 962 <blockquote>
 963 <pre>
 964 #include &lt;math.h&gt;
 965 #include &lt;complex.h&gt;
 966 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf)
 967 </pre>
 968 </blockquote>
 969
 970 <p>This construct is useful because there is no way to separately
 971 initialize the real and imaginary parts of a complex variable in
 972 standard C, given that clang does not support <code>_Imaginary</code>.
 973 (clang also supports the <code>__real__</code> and <code>__imag__</code>
 974 extensions from gcc, which help in some cases, but are not usable in
 975 static initializers.)
 976
 977 <p>Note that this extension does not allow eliding the braces; the
 978 meaning of the following two lines is different:</p>
 979
 980 <blockquote>
 981 <pre>
 982 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1)
 983 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0)
 984 </pre>
 985 </blockquote>
 986
 987 <p>This extension also works in C++ mode, as far as that goes, but does not
 988     apply to the C++ <code>std::complex</code>.  (In C++11, list
 989     initialization allows the same syntax to be used with
 990     <code>std::complex</code> with the same meaning.)
 991
 992 <!-- ======================================================================= -->
 993 <h2 id="builtins">Builtin Functions</h2>
 994 <!-- ======================================================================= -->
 995
 996 <p>Clang supports a number of builtin library functions with the same syntax as
 997 GCC, including things like <tt>__builtin_nan</tt>,
 998 <tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
 999 <tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc.  In
1000 addition to the GCC builtins, Clang supports a number of builtins that GCC does
1001 not, which are listed here.</p>
1002
1003 <p>Please note that Clang does not and will not support all of the GCC builtins
1004 for vector operations.  Instead of using builtins, you should use the functions
1005 defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
1006 define portable wrappers for these.  Many of the Clang versions of these
1007 functions are implemented directly in terms of <a href="#vectors">extended
1008 vector support</a> instead of builtins, in order to reduce the number of
1009 builtins that we need to implement.</p>
1010
1011 <!-- ======================================================================= -->
1012 <h3><a name="__builtin_shufflevector">__builtin_shufflevector</a></h3>
1013 <!-- ======================================================================= -->
1014
1015 <p><tt>__builtin_shufflevector</tt> is used to express generic vector
1016 permutation/shuffle/swizzle operations. This builtin is also very important for
1017 the implementation of various target-specific header files like
1018 <tt>&lt;xmmintrin.h&gt;</tt>.
1019 </p>
1020
1021 <p><b>Syntax:</b></p>
1022
1023 <pre>
1024 __builtin_shufflevector(vec1, vec2, index1, index2, ...)
1025 </pre>
1026
1027 <p><b>Examples:</b></p>
1028
1029 <pre>
1030   // Identity operation - return 4-element vector V1.
1031   __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
1032
1033   // "Splat" element 0 of V1 into a 4-element result.
1034   __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
1035
1036   // Reverse 4-element vector V1.
1037   __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
1038
1039   // Concatenate every other element of 4-element vectors V1 and V2.
1040   __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
1041
1042   // Concatenate every other element of 8-element vectors V1 and V2.
1043   __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
1044 </pre>
1045
1046 <p><b>Description:</b></p>
1047
1048 <p>The first two arguments to __builtin_shufflevector are vectors that have the
1049 same element type.  The remaining arguments are a list of integers that specify
1050 the elements indices of the first two vectors that should be extracted and
1051 returned in a new vector.  These element indices are numbered sequentially
1052 starting with the first vector, continuing into the second vector.  Thus, if
1053 vec1 is a 4-element vector, index 5 would refer to the second element of vec2.
1054 </p>
1055
1056 <p>The result of __builtin_shufflevector is a vector
1057 with the same element type as vec1/vec2 but that has an element count equal to
1058 the number of indices specified.
1059 </p>
1060
1061 <p>Query for this feature with __has_builtin(__builtin_shufflevector).</p>
1062
1063 <!-- ======================================================================= -->
1064 <h3><a name="__builtin_unreachable">__builtin_unreachable</a></h3>
1065 <!-- ======================================================================= -->
1066
1067 <p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in
1068 the program cannot be reached, even if the compiler might otherwise think it
1069 can.  This is useful to improve optimization and eliminates certain warnings.
1070 For example, without the <tt>__builtin_unreachable</tt> in the example below,
1071 the compiler assumes that the inline asm can fall through and prints a "function
1072 declared 'noreturn' should not return" warning.
1073 </p>
1074
1075 <p><b>Syntax:</b></p>
1076
1077 <pre>
1078 __builtin_unreachable()
1079 </pre>
1080
1081 <p><b>Example of Use:</b></p>
1082
1083 <pre>
1084 void myabort(void) __attribute__((noreturn));
1085 void myabort(void) {
1086     asm("int3");
1087     __builtin_unreachable();
1088 }
1089 </pre>
1090
1091 <p><b>Description:</b></p>
1092
1093 <p>The __builtin_unreachable() builtin has completely undefined behavior.  Since
1094 it has undefined behavior, it is a statement that it is never reached and the
1095 optimizer can take advantage of this to produce better code.  This builtin takes
1096 no arguments and produces a void result.
1097 </p>
1098
1099 <p>Query for this feature with __has_builtin(__builtin_unreachable).</p>
1100
1101 <!-- ======================================================================= -->
1102 <h3><a name="__sync_swap">__sync_swap</a></h3>
1103 <!-- ======================================================================= -->
1104
1105 <p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in
1106 memory.
1107 </p>
1108
1109 <p><b>Syntax:</b></p>
1110
1111 <pre>
1112 <i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...)
1113 </pre>
1114
1115 <p><b>Example of Use:</b></p>
1116
1117 <pre>
1118 int old_value = __sync_swap(&amp;value, new_value);
1119 </pre>
1120
1121 <p><b>Description:</b></p>
1122
1123 <p>The __sync_swap() builtin extends the existing __sync_*() family of atomic
1124 intrinsics to allow code to atomically swap the current value with the new
1125 value.  More importantly, it helps developers write more efficient and correct
1126 code by avoiding expensive loops around __sync_bool_compare_and_swap() or
1127 relying on the platform specific implementation details of
1128 __sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier.
1129 </p>
1130
1131
1132 <!-- ======================================================================= -->
1133 <h2 id="targetspecific">Target-Specific Extensions</h2>
1134 <!-- ======================================================================= -->
1135
1136 <p>Clang supports some language features conditionally on some targets.</p>
1137
1138 <!-- ======================================================================= -->
1139 <h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
1140 <!-- ======================================================================= -->
1141
1142 <p>The X86 backend has these language extensions:</p>
1143
1144 <!-- ======================================================================= -->
1145 <h4 id="x86-gs-segment">Memory references off the GS segment</h4>
1146 <!-- ======================================================================= -->
1147
1148 <p>Annotating a pointer with address space #256 causes it to  be code generated
1149 relative to the X86 GS segment register, and address space #257 causes it to be
1150 relative to the X86 FS segment.  Note that this is a very very low-level
1151 feature that should only be used if you know what you're doing (for example in
1152 an OS kernel).</p>
1153
1154 <p>Here is an example:</p>
1155
1156 <pre>
1157 #define GS_RELATIVE __attribute__((address_space(256)))
1158 int foo(int GS_RELATIVE *P) {
1159   return *P;
1160 }
1161 </pre>
1162
1163 <p>Which compiles to (on X86-32):</p>
1164
1165 <pre>
1166 _foo:
1167         movl    4(%esp), %eax
1168         movl    %gs:(%eax), %eax
1169         ret
1170 </pre>
1171
1172 <!-- ======================================================================= -->
1173 <h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
1174 <!-- ======================================================================= -->
1175
1176 <p>Clang supports additional attributes that are useful for documenting program
1177 invariants and rules for static analysis tools. The extensions documented here
1178 are used by the <a
1179 href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
1180 engine</a> that is part of Clang's Analysis library.</p>
1181
1182 <h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3>
1183
1184 <p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
1185 attribute. This attribute, which is typically affixed to a function prototype,
1186 indicates that a call to a given function never returns. Function prototypes for
1187 common functions like <tt>exit</tt> are typically annotated with this attribute,
1188 as well as a variety of common assertion handlers. Users can educate the static
1189 analyzer about their own custom assertion handles (thus cutting down on false
1190 positives due to false paths) by marking their own &quot;panic&quot; functions
1191 with this attribute.</p>
1192
1193 <p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
1194 there are special functions that for all intents and purposes should be
1195 considered panic functions (i.e., they are only called when an internal program
1196 error occurs) but may actually return so that the program can fail gracefully.
1197 The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
1198 as being interpreted as &quot;no return&quot; functions by the analyzer (thus
1199 pruning bogus paths) but will not affect compilation (as in the case of
1200 <tt>noreturn</tt>).</p>
1201
1202 <p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the
1203 same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
1204 placed at the end of function prototypes:</p>
1205
1206 <pre>
1207   void foo() <b>__attribute__((analyzer_noreturn))</b>;
1208 </pre>
1209
1210 <p>Query for this feature with
1211 <tt>__has_attribute(analyzer_noreturn)</tt>.</p>
1212
1213 <h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3>
1214
1215 <p>Many methods in Objective-C have conventional meanings determined
1216 by their selectors.  For the purposes of static analysis, it is
1217 sometimes useful to be able to mark a method as having a particular
1218 conventional meaning despite not having the right selector, or as not
1219 having the conventional meaning that its selector would suggest.
1220 For these use cases, we provide an attribute to specifically describe
1221 the <q>method family</q> that a method belongs to.</p>
1222
1223 <p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>,
1224 where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>,
1225 <tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>.  This attribute
1226 can only be placed at the end of a method declaration:</p>
1227
1228 <pre>
1229   - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>;
1230 </pre>
1231
1232 <p>Users who do not wish to change the conventional meaning of a
1233 method, and who merely want to document its non-standard retain and
1234 release semantics, should use the
1235 <a href="#attr_retain_release">retaining behavior attributes</a>
1236 described below.</p>
1237
1238 <p>Query for this feature with
1239 <tt>__has_attribute(objc_method_family)</tt>.</p>
1240
1241 <h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3>
1242
1243 <p>In Objective-C, functions and methods are generally assumed to take
1244 and return objects with +0 retain counts, with some exceptions for
1245 special methods like <tt>+alloc</tt> and <tt>init</tt>.  However,
1246 there are exceptions, and so Clang provides attributes to allow these
1247 exceptions to be documented, which helps the analyzer find leaks (and
1248 ignore non-leaks).  Some exceptions may be better described using
1249 the <a href="#attr_method_family"><tt>objc_method_family</tt></a>
1250 attribute instead.</p>
1251
1252 <p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>,
1253 <tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>,
1254 and <tt>cf_returns_not_retained</tt> attributes can be placed on
1255 methods and functions that return Objective-C or CoreFoundation
1256 objects.  They are commonly placed at the end of a function prototype
1257 or method declaration:</p>
1258
1259 <pre>
1260   id foo() <b>__attribute__((ns_returns_retained))</b>;
1261
1262   - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>;
1263 </pre>
1264
1265 <p>The <tt>*_returns_retained</tt> attributes specify that the
1266 returned object has a +1 retain count.
1267 The <tt>*_returns_not_retained</tt> attributes specify that the return
1268 object has a +0 retain count, even if the normal convention for its
1269 selector would be +1.  <tt>ns_returns_autoreleased</tt> specifies that the
1270 returned object is +0, but is guaranteed to live at least as long as the
1271 next flush of an autorelease pool.</p>
1272
1273 <p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt>
1274 attributes can be placed on an parameter declaration; they specify
1275 that the argument is expected to have a +1 retain count, which will be
1276 balanced in some way by the function or method.
1277 The <tt>ns_consumes_self</tt> attribute can only be placed on an
1278 Objective-C method; it specifies that the method expects
1279 its <tt>self</tt> parameter to have a +1 retain count, which it will
1280 balance in some way.</p>
1281
1282 <pre>
1283   void <b>foo(__attribute__((ns_consumed))</b> NSString *string);
1284
1285   - (void) bar <b>__attribute__((ns_consumes_self))</b>;
1286   - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x;
1287 </pre>
1288
1289 <p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>,
1290 <tt>__has_attribute(ns_returns_retained)</tt>, etc.</p>
1291
1292 <!-- ======================================================================= -->
1293 <h2 id="dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</h2>
1294 <!-- ======================================================================= -->
1295 <h3 id="address_sanitizer">AddressSanitizer</h3>
1296 <p> Use <code>__has_feature(address_sanitizer)</code>
1297 to check if the code is being built with <a
1298   href="AddressSanitizer.html">AddressSanitizer</a>.
1299 </p>
1300
1301 <!-- ======================================================================= -->
1302 <h2 id="threadsafety">Thread-Safety Annotation Checking</h2>
1303 <!-- ======================================================================= -->
1304
1305 <p>Clang supports additional attributes for checking basic locking policies in
1306 multithreaded programs.
1307 Clang currently parses the following list of attributes, although
1308 <b>the implementation for these annotations is currently in development.</b>
1309 For more details, see the
1310 <a href="http://gcc.gnu.org/wiki/ThreadSafetyAnnotation">GCC implementation</a>.
1311 </p>
1312
1313 <h4 id="ts_noanal">no_thread_safety_analysis</h4>
1314
1315 <p>Use <tt>__attribute__((no_thread_safety_analysis))</tt> on a function
1316 declaration to specify that the thread safety analysis should not be run on that
1317 function. This attribute provides an escape hatch (e.g. for situations when it
1318 is difficult to annotate the locking policy). </p>
1319
1320 <h4 id="ts_lockable">lockable</h4>
1321
1322 <p>Use <tt>__attribute__((lockable))</tt> on a class definition to specify
1323 that it has a lockable type (e.g. a Mutex class). This annotation is primarily
1324 used to check consistency.</p>
1325
1326 <h4 id="ts_scopedlockable">scoped_lockable</h4>
1327
1328 <p>Use <tt>__attribute__((scoped_lockable))</tt> on a class definition to
1329 specify that it has a "scoped" lockable type. Objects of this type will acquire
1330 the lock upon construction and release it upon going out of scope.
1331  This annotation is primarily used to check
1332 consistency.</p>
1333
1334 <h4 id="ts_guardedvar">guarded_var</h4>
1335
1336 <p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to
1337 specify that the variable must be accessed while holding some lock.</p>
1338
1339 <h4 id="ts_ptguardedvar">pt_guarded_var</h4>
1340
1341 <p>Use <tt>__attribute__((pt_guarded_var))</tt> on a pointer declaration to
1342 specify that the pointer must be dereferenced while holding some lock.</p>
1343
1344 <h4 id="ts_guardedby">guarded_by(l)</h4>
1345
1346 <p>Use <tt>__attribute__((guarded_by(l)))</tt> on a variable declaration to
1347 specify that the variable must be accessed while holding lock <tt>l</tt>.</p>
1348
1349 <h4 id="ts_ptguardedby">pt_guarded_by(l)</h4>
1350
1351 <p>Use <tt>__attribute__((pt_guarded_by(l)))</tt> on a pointer declaration to
1352 specify that the pointer must be dereferenced while holding lock <tt>l</tt>.</p>
1353
1354 <h4 id="ts_acquiredbefore">acquired_before(...)</h4>
1355
1356 <p>Use <tt>__attribute__((acquired_before(...)))</tt> on a declaration
1357 of a lockable variable to specify that the lock must be acquired before all
1358 attribute arguments. Arguments must be lockable type, and there must be at
1359 least one argument.</p>
1360
1361 <h4 id="ts_acquiredafter">acquired_after(...)</h4>
1362
1363 <p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration
1364 of a lockable variable to specify that the lock must be acquired after all
1365 attribute arguments. Arguments must be lockable type, and there must be at
1366 least one argument.</p>
1367
1368 <h4 id="ts_elf">exclusive_lock_function(...)</h4>
1369
1370 <p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
1371 declaration to specify that the function acquires all listed locks
1372 exclusively. This attribute takes zero or more arguments: either of lockable
1373 type or integers indexing into function parameters of lockable type. If no
1374 arguments are given, the acquired lock is implicitly <tt>this</tt> of the
1375 enclosing object.</p>
1376
1377 <h4 id="ts_slf">shared_lock_function(...)</h4>
1378
1379 <p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
1380 declaration to specify that the function acquires all listed locks, although
1381  the locks may be shared (e.g. read locks). This attribute takes zero or more
1382 arguments: either of lockable type or integers indexing into function
1383 parameters of lockable type. If no arguments are given, the acquired lock is
1384 implicitly <tt>this</tt> of the enclosing object.</p>
1385
1386 <h4 id="ts_etf">exclusive_trylock_function(...)</h4>
1387
1388 <p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
1389 declaration to specify that the function will try (without blocking) to acquire
1390 all listed locks exclusively. This attribute takes one or more arguments. The
1391 first argument is an integer or boolean value specifying the return value of a
1392 successful lock acquisition. The remaining arugments are either of lockable type
1393 or integers indexing into function parameters of lockable type. If only one
1394 argument is given, the acquired lock is implicitly <tt>this</tt> of the
1395 enclosing object.</p>
1396
1397 <h4 id="ts_stf">shared_trylock_function(...)</h4>
1398
1399 <p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
1400 declaration to specify that the function will try (without blocking) to acquire
1401 all listed locks, although the locks may be shared (e.g. read locks). This
1402 attribute takes one or more arguments. The first argument is an integer or
1403 boolean value specifying the return value of a successful lock acquisition. The
1404 remaining arugments are either of lockable type or integers indexing into
1405 function parameters of lockable type. If only one argument is given, the
1406 acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
1407
1408 <h4 id="ts_uf">unlock_function(...)</h4>
1409
1410 <p>Use <tt>__attribute__((unlock_function(...)))</tt> on a function
1411 declaration to specify that the function release all listed locks. This
1412 attribute takes zero or more arguments: either of lockable type or integers
1413 indexing into function parameters of lockable type. If no arguments are given,
1414 the acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
1415
1416 <h4 id="ts_lr">lock_returned(l)</h4>
1417
1418 <p>Use <tt>__attribute__((lock_returned(l)))</tt> on a function
1419 declaration to specify that the function returns lock <tt>l</tt> (<tt>l</tt>
1420 must be of lockable type). This annotation is used to aid in resolving lock
1421 expressions.</p>
1422
1423 <h4 id="ts_le">locks_excluded(...)</h4>
1424
1425 <p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration
1426 to specify that the function must not be called with the listed locks. Arguments
1427 must be lockable type, and there must be at least one argument.</p>
1428
1429 <h4 id="ts_elr">exclusive_locks_required(...)</h4>
1430
1431 <p>Use <tt>__attribute__((exclusive_locks_required(...)))</tt> on a function
1432 declaration to specify that the function must be called while holding the listed
1433 exclusive locks. Arguments must be lockable type, and there must be at
1434 least one argument.</p>
1435
1436 <h4 id="ts_slr">shared_locks_required(...)</h4>
1437
1438 <p>Use <tt>__attribute__((shared_locks_required(...)))</tt> on a function
1439 declaration to specify that the function must be called while holding the listed
1440 shared locks. Arguments must be lockable type, and there must be at
1441 least one argument.</p>
1442
1443 </div>
1444 </body>
1445 </html>