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 th { background-color: #ffddaa; } 15 </style> 16 </head> 17 <body> 18 19 <!--#include virtual="../menu.html.incl"--> 20 21 <div id="content"> 22 23 <h1>Clang Language Extensions</h1> 24 25 <ul> 26 <li><a href="#intro">Introduction</a></li> 27 <li><a href="#feature_check">Feature Checking Macros</a></li> 28 <li><a href="#has_include">Include File Checking Macros</a></li> 29 <li><a href="#builtinmacros">Builtin Macros</a></li> 30 <li><a href="#vectors">Vectors and Extended Vectors</a></li> 31 <li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li> 32 <li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li> 33 <li><a href="#user_specified_system_framework">'User-Specified' System Frameworks</a></li> 34 <li><a href="#availability">Availability attribute</a></li> 35 <li><a href="#checking_language_features">Checks for Standard Language Features</a> 36 <ul> 37 <li><a href="#cxx98">C++98</a> 38 <ul> 39 <li><a href="#cxx_exceptions">C++ exceptions</a></li> 40 <li><a href="#cxx_rtti">C++ RTTI</a></li> 41 </ul></li> 42 <li><a href="#cxx11">C++11</a> 43 <ul> 44 <li><a href="#cxx_access_control_sfinae">C++11 SFINAE includes access control</a></li> 45 <li><a href="#cxx_alias_templates">C++11 alias templates</a></li> 46 <li><a href="#cxx_alignas">C++11 alignment specifiers</a></li> 47 <li><a href="#cxx_attributes">C++11 attributes</a></li> 48 <li><a href="#cxx_constexpr">C++11 generalized constant expressions</a></li> 49 <li><a href="#cxx_decltype">C++11 <tt>decltype()</tt></a></li> 50 <li><a href="#cxx_default_function_template_args">C++11 default template arguments in function templates</a></li> 51 <li><a href="#cxx_defaulted_functions">C++11 defaulted functions</a></li> 52 <li><a href="#cxx_delegating_constructor">C++11 delegating constructors</a></li> 53 <li><a href="#cxx_deleted_functions">C++11 deleted functions</a></li> 54 <li><a href="#cxx_explicit_conversions">C++11 explicit conversion functions</a></li> 55 <li><a href="#cxx_generalized_initializers">C++11 generalized initializers</a></li> 56 <li><a href="#cxx_implicit_moves">C++11 implicit move constructors/assignment operators</a></li> 57 <li><a href="#cxx_inheriting_constructors">C++11 inheriting constructors</a></li> 58 <li><a href="#cxx_inline_namespaces">C++11 inline namespaces</a></li> 59 <li><a href="#cxx_lambdas">C++11 lambdas</a></li> 60 <li><a href="#cxx_local_type_template_args">C++11 local and unnamed types as template arguments</a></li> 61 <li><a href="#cxx_noexcept">C++11 noexcept specification</a></li> 62 <li><a href="#cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</a></li> 63 <li><a href="#cxx_nullptr">C++11 nullptr</a></li> 64 <li><a href="#cxx_override_control">C++11 override control</a></li> 65 <li><a href="#cxx_range_for">C++11 range-based for loop</a></li> 66 <li><a href="#cxx_raw_string_literals">C++11 raw string literals</a></li> 67 <li><a href="#cxx_rvalue_references">C++11 rvalue references</a></li> 68 <li><a href="#cxx_reference_qualified_functions">C++11 reference-qualified functions</a></li> 69 <li><a href="#cxx_static_assert">C++11 <tt>static_assert()</tt></a></li> 70 <li><a href="#cxx_auto_type">C++11 type inference</a></li> 71 <li><a href="#cxx_strong_enums">C++11 strongly-typed enumerations</a></li> 72 <li><a href="#cxx_trailing_return">C++11 trailing return type</a></li> 73 <li><a href="#cxx_unicode_literals">C++11 Unicode string literals</a></li> 74 <li><a href="#cxx_unrestricted_unions">C++11 unrestricted unions</a></li> 75 <li><a href="#cxx_user_literals">C++11 user-defined literals</a></li> 76 <li><a href="#cxx_variadic_templates">C++11 variadic templates</a></li> 77 </ul></li> 78 <li><a href="#c11">C11</a> 79 <ul> 80 <li><a href="#c_alignas">C11 alignment specifiers</a></li> 81 <li><a href="#c_atomic">C11 atomic operations</a></li> 82 <li><a href="#c_generic_selections">C11 generic selections</a></li> 83 <li><a href="#c_static_assert">C11 <tt>_Static_assert()</tt></a></li> 84 </ul></li> 85 </ul></li> 86 <li><a href="#checking_type_traits">Checks for Type Traits</a></li> 87 <li><a href="#blocks">Blocks</a></li> 88 <li><a href="#objc_features">Objective-C Features</a> 89 <ul> 90 <li><a href="#objc_instancetype">Related result types</a></li> 91 <li><a href="#objc_arc">Automatic reference counting</a></li> 92 <li><a href="#objc_fixed_enum">Enumerations with a fixed underlying type</a></li> 93 <li><a href="#objc_lambdas">Interoperability with C++11 lambdas</a></li> 94 <li><a href="#objc_object_literals_subscripting">Object Literals and Subscripting</a></li> 95 </ul> 96 </li> 97 <li><a href="#overloading-in-c">Function Overloading in C</a></li> 98 <li><a href="#complex-list-init">Initializer lists for complex numbers in C</a></li> 99 <li><a href="#builtins">Builtin Functions</a> 100 <ul> 101 <li><a href="#__builtin_readcyclecounter">__builtin_readcyclecounter</a></li> 102 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li> 103 <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li> 104 <li><a href="#__sync_swap">__sync_swap</a></li> 105 </ul> 106 </li> 107 <li><a href="#non-standard-attributes">Non-standard C++11 Attributes</a> 108 <ul> 109 <li><a href="#clang__fallthrough">The <tt>clang::fallthrough</tt> attribute</a></li> 110 </ul> 111 </li> 112 <li><a href="#targetspecific">Target-Specific Extensions</a> 113 <ul> 114 <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li> 115 </ul> 116 </li> 117 <li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li> 118 <li><a href="#dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</a> 119 <ul> 120 <li><a href="#address_sanitizer">AddressSanitizer</a></li> 121 </ul> 122 </li> 123 <li><a href="#threadsafety">Thread Safety Annotation Checking</a> 124 <ul> 125 <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li> 126 <li><a href="#ts_lockable"><tt>lockable</tt></a></li> 127 <li><a href="#ts_scopedlockable"><tt>scoped_lockable</tt></a></li> 128 <li><a href="#ts_guardedvar"><tt>guarded_var</tt></a></li> 129 <li><a href="#ts_ptguardedvar"><tt>pt_guarded_var</tt></a></li> 130 <li><a href="#ts_guardedby"><tt>guarded_by(l)</tt></a></li> 131 <li><a href="#ts_ptguardedby"><tt>pt_guarded_by(l)</tt></a></li> 132 <li><a href="#ts_acquiredbefore"><tt>acquired_before(...)</tt></a></li> 133 <li><a href="#ts_acquiredafter"><tt>acquired_after(...)</tt></a></li> 134 <li><a href="#ts_elf"><tt>exclusive_lock_function(...)</tt></a></li> 135 <li><a href="#ts_slf"><tt>shared_lock_function(...)</tt></a></li> 136 <li><a href="#ts_etf"><tt>exclusive_trylock_function(...)</tt></a></li> 137 <li><a href="#ts_stf"><tt>shared_trylock_function(...)</tt></a></li> 138 <li><a href="#ts_uf"><tt>unlock_function(...)</tt></a></li> 139 <li><a href="#ts_lr"><tt>lock_returned(l)</tt></a></li> 140 <li><a href="#ts_le"><tt>locks_excluded(...)</tt></a></li> 141 <li><a href="#ts_elr"><tt>exclusive_locks_required(...)</tt></a></li> 142 <li><a href="#ts_slr"><tt>shared_locks_required(...)</tt></a></li> 143 </ul> 144 </li> 145 <li><a href="#type_safety">Type Safety Checking</a> 146 <ul> 147 <li><a href="#argument_with_type_tag"><tt>argument_with_type_tag(...)</tt></a></li> 148 <li><a href="#pointer_with_type_tag"><tt>pointer_with_type_tag(...)</tt></a></li> 149 <li><a href="#type_tag_for_datatype"><tt>type_tag_for_datatype(...)</tt></a></li> 150 </ul> 151 </li> 152 </ul> 153 154 <!-- ======================================================================= --> 155 <h2 id="intro">Introduction</h2> 156 <!-- ======================================================================= --> 157 158 <p>This document describes the language extensions provided by Clang. In 159 addition to the language extensions listed here, Clang aims to support a broad 160 range of GCC extensions. Please see the <a 161 href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for 162 more information on these extensions.</p> 163 164 <!-- ======================================================================= --> 165 <h2 id="feature_check">Feature Checking Macros</h2> 166 <!-- ======================================================================= --> 167 168 <p>Language extensions can be very useful, but only if you know you can depend 169 on them. In order to allow fine-grain features checks, we support three builtin 170 function-like macros. This allows you to directly test for a feature in your 171 code without having to resort to something like autoconf or fragile "compiler 172 version checks".</p> 173 174 <!-- ======================================================================= --> 175 <h3><a name="__has_builtin">__has_builtin</a></h3> 176 <!-- ======================================================================= --> 177 178 <p>This function-like macro takes a single identifier argument that is the name 179 of a builtin function. It evaluates to 1 if the builtin is supported or 0 if 180 not. It can be used like this:</p> 181 182 <blockquote> 183 <pre> 184 #ifndef __has_builtin // Optional of course. 185 #define __has_builtin(x) 0 // Compatibility with non-clang compilers. 186 #endif 187 188 ... 189 #if __has_builtin(__builtin_trap) 190 __builtin_trap(); 191 #else 192 abort(); 193 #endif 194 ... 195 </pre> 196 </blockquote> 197 198 199 <!-- ======================================================================= --> 200 <h3><a name="__has_feature_extension"> __has_feature and __has_extension</a></h3> 201 <!-- ======================================================================= --> 202 203 <p>These function-like macros take a single identifier argument that is the 204 name of a feature. <code>__has_feature</code> evaluates to 1 if the feature 205 is both supported by Clang and standardized in the current language standard 206 or 0 if not (but see <a href="#has_feature_back_compat">below</a>), while 207 <code>__has_extension</code> evaluates to 1 if the feature is supported by 208 Clang in the current language (either as a language extension or a standard 209 language feature) or 0 if not. They can be used like this:</p> 210 211 <blockquote> 212 <pre> 213 #ifndef __has_feature // Optional of course. 214 #define __has_feature(x) 0 // Compatibility with non-clang compilers. 215 #endif 216 #ifndef __has_extension 217 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers. 218 #endif 219 220 ... 221 #if __has_feature(cxx_rvalue_references) 222 // This code will only be compiled with the -std=c++11 and -std=gnu++11 223 // options, because rvalue references are only standardized in C++11. 224 #endif 225 226 #if __has_extension(cxx_rvalue_references) 227 // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98 228 // and -std=gnu++98 options, because rvalue references are supported as a 229 // language extension in C++98. 230 #endif 231 </pre> 232 </blockquote> 233 234 <p id="has_feature_back_compat">For backwards compatibility reasons, 235 <code>__has_feature</code> can also be used to test for support for 236 non-standardized features, i.e. features not prefixed <code>c_</code>, 237 <code>cxx_</code> or <code>objc_</code>.</p> 238 239 <p id="has_feature_for_non_language_features"> 240 Another use of <code>__has_feature</code> is to check for compiler features 241 not related to the language standard, such as e.g. 242 <a href="AddressSanitizer.html">AddressSanitizer</a>. 243 244 <p>If the <code>-pedantic-errors</code> option is given, 245 <code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p> 246 247 <p>The feature tag is described along with the language feature below.</p> 248 249 <p>The feature name or extension name can also be specified with a preceding and 250 following <code>__</code> (double underscore) to avoid interference from a macro 251 with the same name. For instance, <code>__cxx_rvalue_references__</code> can be 252 used instead of <code>cxx_rvalue_references</code>.</p> 253 254 <!-- ======================================================================= --> 255 <h3><a name="__has_attribute">__has_attribute</a></h3> 256 <!-- ======================================================================= --> 257 258 <p>This function-like macro takes a single identifier argument that is the name 259 of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It 260 can be used like this:</p> 261 262 <blockquote> 263 <pre> 264 #ifndef __has_attribute // Optional of course. 265 #define __has_attribute(x) 0 // Compatibility with non-clang compilers. 266 #endif 267 268 ... 269 #if __has_attribute(always_inline) 270 #define ALWAYS_INLINE __attribute__((always_inline)) 271 #else 272 #define ALWAYS_INLINE 273 #endif 274 ... 275 </pre> 276 </blockquote> 277 278 <p>The attribute name can also be specified with a preceding and 279 following <code>__</code> (double underscore) to avoid interference from a macro 280 with the same name. For instance, <code>__always_inline__</code> can be used 281 instead of <code>always_inline</code>.</p> 282 283 <!-- ======================================================================= --> 284 <h2 id="has_include">Include File Checking Macros</h2> 285 <!-- ======================================================================= --> 286 287 <p>Not all developments systems have the same include files. 288 The <a href="#__has_include">__has_include</a> and 289 <a href="#__has_include_next">__has_include_next</a> macros allow you to 290 check for the existence of an include file before doing 291 a possibly failing #include directive.</p> 292 293 <!-- ======================================================================= --> 294 <h3><a name="__has_include">__has_include</a></h3> 295 <!-- ======================================================================= --> 296 297 <p>This function-like macro takes a single file name string argument that 298 is the name of an include file. It evaluates to 1 if the file can 299 be found using the include paths, or 0 otherwise:</p> 300 301 <blockquote> 302 <pre> 303 // Note the two possible file name string formats. 304 #if __has_include("myinclude.h") && __has_include(<stdint.h>) 305 # include "myinclude.h" 306 #endif 307 308 // To avoid problem with non-clang compilers not having this macro. 309 #if defined(__has_include) && __has_include("myinclude.h") 310 # include "myinclude.h" 311 #endif 312 </pre> 313 </blockquote> 314 315 <p>To test for this feature, use #if defined(__has_include).</p> 316 317 <!-- ======================================================================= --> 318 <h3><a name="__has_include_next">__has_include_next</a></h3> 319 <!-- ======================================================================= --> 320 321 <p>This function-like macro takes a single file name string argument that 322 is the name of an include file. It is like __has_include except that it 323 looks for the second instance of the given file found in the include 324 paths. It evaluates to 1 if the second instance of the file can 325 be found using the include paths, or 0 otherwise:</p> 326 327 <blockquote> 328 <pre> 329 // Note the two possible file name string formats. 330 #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>) 331 # include_next "myinclude.h" 332 #endif 333 334 // To avoid problem with non-clang compilers not having this macro. 335 #if defined(__has_include_next) && __has_include_next("myinclude.h") 336 # include_next "myinclude.h" 337 #endif 338 </pre> 339 </blockquote> 340 341 <p>Note that __has_include_next, like the GNU extension 342 #include_next directive, is intended for use in headers only, 343 and will issue a warning if used in the top-level compilation 344 file. A warning will also be issued if an absolute path 345 is used in the file argument.</p> 346 347 348 <!-- ======================================================================= --> 349 <h3><a name="__has_warning">__has_warning</a></h3> 350 <!-- ======================================================================= --> 351 352 <p>This function-like macro takes a string literal that represents a command 353 line option for a warning and returns true if that is a valid warning 354 option.</p> 355 356 <blockquote> 357 <pre> 358 #if __has_warning("-Wformat") 359 ... 360 #endif 361 </pre> 362 </blockquote> 363 364 <!-- ======================================================================= --> 365 <h2 id="builtinmacros">Builtin Macros</h2> 366 <!-- ======================================================================= --> 367 368 <dl> 369 <dt><code>__BASE_FILE__</code></dt> 370 <dd>Defined to a string that contains the name of the main input 371 file passed to Clang.</dd> 372 373 <dt><code>__COUNTER__</code></dt> 374 <dd>Defined to an integer value that starts at zero and is 375 incremented each time the <code>__COUNTER__</code> macro is 376 expanded.</dd> 377 378 <dt><code>__INCLUDE_LEVEL__</code></dt> 379 <dd>Defined to an integral value that is the include depth of the 380 file currently being translated. For the main file, this value is 381 zero.</dd> 382 383 <dt><code>__TIMESTAMP__</code></dt> 384 <dd>Defined to the date and time of the last modification of the 385 current source file.</dd> 386 387 <dt><code>__clang__</code></dt> 388 <dd>Defined when compiling with Clang</dd> 389 390 <dt><code>__clang_major__</code></dt> 391 <dd>Defined to the major marketing version number of Clang (e.g., the 392 2 in 2.0.1). Note that marketing version numbers should not be used to 393 check for language features, as different vendors use different numbering 394 schemes. Instead, use the <a href="#feature_check">feature checking 395 macros</a>.</dd> 396 397 <dt><code>__clang_minor__</code></dt> 398 <dd>Defined to the minor version number of Clang (e.g., the 0 in 399 2.0.1). Note that marketing version numbers should not be used to 400 check for language features, as different vendors use different numbering 401 schemes. Instead, use the <a href="#feature_check">feature checking 402 macros</a>.</dd> 403 404 <dt><code>__clang_patchlevel__</code></dt> 405 <dd>Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).</dd> 406 407 <dt><code>__clang_version__</code></dt> 408 <dd>Defined to a string that captures the Clang marketing version, including 409 the Subversion tag or revision number, e.g., "1.5 (trunk 102332)".</dd> 410 </dl> 411 412 <!-- ======================================================================= --> 413 <h2 id="vectors">Vectors and Extended Vectors</h2> 414 <!-- ======================================================================= --> 415 416 <p>Supports the GCC, OpenCL, AltiVec and NEON vector extensions.</p> 417 418 <p>OpenCL vector types are created using <tt>ext_vector_type</tt> attribute. It 419 support for <tt>V.xyzw</tt> syntax and other tidbits as seen in OpenCL. An 420 example is:</p> 421 422 <blockquote> 423 <pre> 424 typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>; 425 typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>; 426 427 float4 foo(float2 a, float2 b) { 428 float4 c; 429 c.xz = a; 430 c.yw = b; 431 return c; 432 } 433 </pre> 434 </blockquote> 435 436 <p>Query for this feature with 437 <tt>__has_extension(attribute_ext_vector_type)</tt>.</p> 438 439 <p>Giving <tt>-faltivec</tt> option to clang enables support for AltiVec vector 440 syntax and functions. For example:</p> 441 442 <blockquote> 443 <pre> 444 vector float foo(vector int a) { 445 vector int b; 446 b = vec_add(a, a) + a; 447 return (vector float)b; 448 } 449 </pre> 450 </blockquote> 451 452 <p>NEON vector types are created using <tt>neon_vector_type</tt> and 453 <tt>neon_polyvector_type</tt> attributes. For example:</p> 454 455 <blockquote> 456 <pre> 457 typedef <b>__attribute__((neon_vector_type(8)))</b> int8_t int8x8_t; 458 typedef <b>__attribute__((neon_polyvector_type(16)))</b> poly8_t poly8x16_t; 459 460 int8x8_t foo(int8x8_t a) { 461 int8x8_t v; 462 v = a; 463 return v; 464 } 465 </pre> 466 </blockquote> 467 468 <!-- ======================================================================= --> 469 <h3><a name="vector_literals">Vector Literals</a></h3> 470 <!-- ======================================================================= --> 471 472 <p>Vector literals can be used to create vectors from a set of scalars, or 473 vectors. Either parentheses or braces form can be used. In the parentheses form 474 the number of literal values specified must be one, i.e. referring to a scalar 475 value, or must match the size of the vector type being created. If a single 476 scalar literal value is specified, the scalar literal value will be replicated 477 to all the components of the vector type. In the brackets form any number of 478 literals can be specified. For example:</p> 479 480 <blockquote> 481 <pre> 482 typedef int v4si __attribute__((__vector_size__(16))); 483 typedef float float4 __attribute__((ext_vector_type(4))); 484 typedef float float2 __attribute__((ext_vector_type(2))); 485 486 v4si vsi = (v4si){1, 2, 3, 4}; 487 float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f); 488 vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1). 489 vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0). 490 vector int vi3 = (vector int)(1, 2); // error 491 vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0). 492 vector int vi5 = (vector int)(1, 2, 3, 4); 493 float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f)); 494 </pre> 495 </blockquote> 496 497 <!-- ======================================================================= --> 498 <h3><a name="vector_operations">Vector Operations</a></h3> 499 <!-- ======================================================================= --> 500 501 <p>The table below shows the support for each operation by vector extension. 502 A dash indicates that an operation is not accepted according to a corresponding 503 specification.</p> 504 505 <table width="500" border="1" cellspacing="0"> 506 <tr> 507 <th>Operator</th> 508 <th>OpenCL</th> 509 <th>AltiVec</th> 510 <th>GCC</th> 511 <th>NEON</th> 512 </tr> 513 <tr> 514 <td>[]</td> 515 <td align="center">yes</td> 516 <td align="center">yes</td> 517 <td align="center">yes</td> 518 <td align="center">-</td> 519 </tr> 520 <tr> 521 <td>unary operators +, -</td> 522 <td align="center">yes</td> 523 <td align="center">yes</td> 524 <td align="center">yes</td> 525 <td align="center">-</td> 526 </tr> 527 <tr> 528 <td>++, --</td> 529 <td align="center">yes</td> 530 <td align="center">yes</td> 531 <td align="center">-</td> 532 <td align="center">-</td> 533 </tr> 534 <tr> 535 <td>+, -, *, /, %</td> 536 <td align="center">yes</td> 537 <td align="center">yes</td> 538 <td align="center">yes</td> 539 <td align="center">-</td> 540 </tr> 541 <tr> 542 <td>bitwise operators &, |, ^, ~</td> 543 <td align="center">yes</td> 544 <td align="center">yes</td> 545 <td align="center">yes</td> 546 <td align="center">-</td> 547 </tr> 548 <tr> 549 <td>>>, <<</td> 550 <td align="center">yes</td> 551 <td align="center">yes</td> 552 <td align="center">yes</td> 553 <td align="center">-</td> 554 </tr> 555 <tr> 556 <td>!, &&,||</td> 557 <td align="center">no</td> 558 <td align="center">-</td> 559 <td align="center">-</td> 560 <td align="center">-</td> 561 </tr> 562 <tr> 563 <td>==,!=, >, <, >=, <=</td> 564 <td align="center">yes</td> 565 <td align="center">yes</td> 566 <td align="center">-</td> 567 <td align="center">-</td> 568 </tr> 569 <tr> 570 <td>=</td> 571 <td align="center">yes</td> 572 <td align="center">yes</td> 573 <td align="center">yes</td> 574 <td align="center">yes</td> 575 </tr> 576 <tr> 577 <td>:?</td> 578 <td align="center">yes</td> 579 <td align="center">-</td> 580 <td align="center">-</td> 581 <td align="center">-</td> 582 </tr> 583 <tr> 584 <td>sizeof</td> 585 <td align="center">yes</td> 586 <td align="center">yes</td> 587 <td align="center">yes</td> 588 <td align="center">yes</td> 589 </tr> 590 </table> 591 592 <p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p> 593 594 <!-- ======================================================================= --> 595 <h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2> 596 <!-- ======================================================================= --> 597 598 <p>An optional string message can be added to the <tt>deprecated</tt> 599 and <tt>unavailable</tt> attributes. For example:</p> 600 601 <blockquote> 602 <pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre> 603 </blockquote> 604 605 <p>If the deprecated or unavailable declaration is used, the message 606 will be incorporated into the appropriate diagnostic:</p> 607 608 <blockquote> 609 <pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! 610 [-Wdeprecated-declarations] 611 explode(); 612 ^</pre> 613 </blockquote> 614 615 <p>Query for this feature 616 with <tt>__has_extension(attribute_deprecated_with_message)</tt> 617 and <tt>__has_extension(attribute_unavailable_with_message)</tt>.</p> 618 619 <!-- ======================================================================= --> 620 <h2 id="attributes-on-enumerators">Attributes on Enumerators</h2> 621 <!-- ======================================================================= --> 622 623 <p>Clang allows attributes to be written on individual enumerators. 624 This allows enumerators to be deprecated, made unavailable, etc. The 625 attribute must appear after the enumerator name and before any 626 initializer, like so:</p> 627 628 <blockquote> 629 <pre>enum OperationMode { 630 OM_Invalid, 631 OM_Normal, 632 OM_Terrified __attribute__((deprecated)), 633 OM_AbortOnError __attribute__((deprecated)) = 4 634 };</pre> 635 </blockquote> 636 637 <p>Attributes on the <tt>enum</tt> declaration do not apply to 638 individual enumerators.</p> 639 640 <p>Query for this feature with <tt>__has_extension(enumerator_attributes)</tt>.</p> 641 642 <!-- ======================================================================= --> 643 <h2 id="user_specified_system_framework">'User-Specified' System Frameworks</h2> 644 <!-- ======================================================================= --> 645 646 <p>Clang provides a mechanism by which frameworks can be built in such a way 647 that they will always be treated as being 'system frameworks', even if they are 648 not present in a system framework directory. This can be useful to system 649 framework developers who want to be able to test building other applications 650 with development builds of their framework, including the manner in which the 651 compiler changes warning behavior for system headers.</p> 652 653 <p>Framework developers can opt-in to this mechanism by creating a 654 '.system_framework' file at the top-level of their framework. That is, the 655 framework should have contents like:</p> 656 657 <pre> 658 .../TestFramework.framework 659 .../TestFramework.framework/.system_framework 660 .../TestFramework.framework/Headers 661 .../TestFramework.framework/Headers/TestFramework.h 662 ... 663 </pre> 664 665 <p>Clang will treat the presence of this file as an indicator that the framework 666 should be treated as a system framework, regardless of how it was found in the 667 framework search path. For consistency, we recommend that such files never be 668 included in installed versions of the framework.</p> 669 670 <!-- ======================================================================= --> 671 <h2 id="availability">Availability attribute</h2> 672 <!-- ======================================================================= --> 673 674 <p>Clang introduces the <code>availability</code> attribute, which can 675 be placed on declarations to describe the lifecycle of that 676 declaration relative to operating system versions. Consider the function declaration for a hypothetical function <code>f</code>:</p> 677 678 <pre> 679 void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7))); 680 </pre> 681 682 <p>The availability attribute states that <code>f</code> was introduced in Mac OS X 10.4, deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information is used by Clang to determine when it is safe to use <code>f</code>: for example, if Clang is instructed to compile code for Mac OS X 10.5, a call to <code>f()</code> succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call succeeds but Clang emits a warning specifying that the function is deprecated. Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call fails because <code>f()</code> is no longer available.</p> 683 684 <p>The availablility attribute is a comma-separated list starting with the platform name and then including clauses specifying important milestones in the declaration's lifetime (in any order) along with additional information. Those clauses can be:</p> 685 686 <dl> 687 <dt>introduced=<i>version</i></dt> 688 <dd>The first version in which this declaration was introduced.</dd> 689 690 <dt>deprecated=<i>version</i></dt> 691 <dd>The first version in which this declaration was deprecated, meaning that users should migrate away from this API.</dd> 692 693 <dt>obsoleted=<i>version</i></dt> 694 <dd>The first version in which this declaration was obsoleted, meaning that it was removed completely and can no longer be used.</dd> 695 696 <dt>unavailable</dt> 697 <dd>This declaration is never available on this platform.</dd> 698 699 <dt>message=<i>string-literal</i></dt> 700 <dd>Additional message text that Clang will provide when emitting a warning or error about use of a deprecated or obsoleted declaration. Useful to direct users to replacement APIs.</dd> 701 </dl> 702 703 <p>Multiple availability attributes can be placed on a declaration, which may correspond to different platforms. Only the availability attribute with the platform corresponding to the target platform will be used; any others will be ignored. If no availability attribute specifies availability for the current target platform, the availability attributes are ignored. Supported platforms are:</p> 704 705 <dl> 706 <dt>ios</dt> 707 <dd>Apple's iOS operating system. The minimum deployment target is specified by the <code>-mios-version-min=<i>version</i></code> or <code>-miphoneos-version-min=<i>version</i></code> command-line arguments.</dd> 708 709 <dt>macosx</dt> 710 <dd>Apple's Mac OS X operating system. The minimum deployment target is specified by the <code>-mmacosx-version-min=<i>version</i></code> command-line argument.</dd> 711 </dl> 712 713 <p>A declaration can be used even when deploying back to a platform 714 version prior to when the declaration was introduced. When this 715 happens, the declaration is <a 716 href="https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html">weakly 717 linked</a>, as if the <code>weak_import</code> attribute were added to the declaration. A weakly-linked declaration may or may not be present a run-time, and a program can determine whether the declaration is present by checking whether the address of that declaration is non-NULL.</p> 718 719 <!-- ======================================================================= --> 720 <h2 id="checking_language_features">Checks for Standard Language Features</h2> 721 <!-- ======================================================================= --> 722 723 <p>The <tt>__has_feature</tt> macro can be used to query if certain standard 724 language features are enabled. The <tt>__has_extension</tt> macro can be used 725 to query if language features are available as an extension when compiling for 726 a standard which does not provide them. The features which can be tested are 727 listed here.</p> 728 729 <h3 id="cxx98">C++98</h3> 730 731 <p>The features listed below are part of the C++98 standard. These features are 732 enabled by default when compiling C++ code.</p> 733 734 <h4 id="cxx_exceptions">C++ exceptions</h4> 735 736 <p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For 737 example, compiling code with <tt>-fno-exceptions</tt> disables C++ exceptions.</p> 738 739 <h4 id="cxx_rtti">C++ RTTI</h4> 740 741 <p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example, 742 compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p> 743 744 <h3 id="cxx11">C++11</h3> 745 746 <p>The features listed below are part of the C++11 standard. As a result, all 747 these features are enabled with the <tt>-std=c++11</tt> or <tt>-std=gnu++11</tt> 748 option when compiling C++ code.</p> 749 750 <h4 id="cxx_access_control_sfinae">C++11 SFINAE includes access control</h4> 751 752 <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> 753 754 <h4 id="cxx_alias_templates">C++11 alias templates</h4> 755 756 <p>Use <tt>__has_feature(cxx_alias_templates)</tt> or 757 <tt>__has_extension(cxx_alias_templates)</tt> to determine if support for 758 C++11's alias declarations and alias templates is enabled.</p> 759 760 <h4 id="cxx_alignas">C++11 alignment specifiers</h4> 761 762 <p>Use <tt>__has_feature(cxx_alignas)</tt> or 763 <tt>__has_extension(cxx_alignas)</tt> to determine if support for alignment 764 specifiers using <tt>alignas</tt> is enabled.</p> 765 766 <h4 id="cxx_attributes">C++11 attributes</h4> 767 768 <p>Use <tt>__has_feature(cxx_attributes)</tt> or 769 <tt>__has_extension(cxx_attributes)</tt> to determine if support for attribute 770 parsing with C++11's square bracket notation is enabled.</p> 771 772 <h4 id="cxx_constexpr">C++11 generalized constant expressions</h4> 773 774 <p>Use <tt>__has_feature(cxx_constexpr)</tt> to determine if support 775 for generalized constant expressions (e.g., <tt>constexpr</tt>) is 776 enabled.</p> 777 778 <h4 id="cxx_decltype">C++11 <tt>decltype()</tt></h4> 779 780 <p>Use <tt>__has_feature(cxx_decltype)</tt> or 781 <tt>__has_extension(cxx_decltype)</tt> to determine if support for the 782 <tt>decltype()</tt> specifier is enabled. C++11's <tt>decltype</tt> 783 does not require type-completeness of a function call expression. 784 Use <tt>__has_feature(cxx_decltype_incomplete_return_types)</tt> 785 or <tt>__has_extension(cxx_decltype_incomplete_return_types)</tt> 786 to determine if support for this feature is enabled.</p> 787 788 <h4 id="cxx_default_function_template_args">C++11 default template arguments in function templates</h4> 789 790 <p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or 791 <tt>__has_extension(cxx_default_function_template_args)</tt> to determine 792 if support for default template arguments in function templates is enabled.</p> 793 794 <h4 id="cxx_defaulted_functions">C++11 <tt>default</tt>ed functions</h4> 795 796 <p>Use <tt>__has_feature(cxx_defaulted_functions)</tt> or 797 <tt>__has_extension(cxx_defaulted_functions)</tt> to determine if support for 798 defaulted function definitions (with <tt>= default</tt>) is enabled.</p> 799 800 <h4 id="cxx_delegating_constructors">C++11 delegating constructors</h4> 801 802 <p>Use <tt>__has_feature(cxx_delegating_constructors)</tt> to determine if 803 support for delegating constructors is enabled.</p> 804 805 <h4 id="cxx_deleted_functions">C++11 <tt>delete</tt>d functions</h4> 806 807 <p>Use <tt>__has_feature(cxx_deleted_functions)</tt> or 808 <tt>__has_extension(cxx_deleted_functions)</tt> to determine if support for 809 deleted function definitions (with <tt>= delete</tt>) is enabled.</p> 810 811 <h4 id="cxx_explicit_conversions">C++11 explicit conversion functions</h4> 812 <p>Use <tt>__has_feature(cxx_explicit_conversions)</tt> to determine if support for <tt>explicit</tt> conversion functions is enabled.</p> 813 814 <h4 id="cxx_generalized_initializers">C++11 generalized initializers</h4> 815 816 <p>Use <tt>__has_feature(cxx_generalized_initializers)</tt> to determine if 817 support for generalized initializers (using braced lists and 818 <tt>std::initializer_list</tt>) is enabled.</p> 819 820 <h4 id="cxx_implicit_moves">C++11 implicit move constructors/assignment operators</h4> 821 822 <p>Use <tt>__has_feature(cxx_implicit_moves)</tt> to determine if Clang will 823 implicitly generate move constructors and move assignment operators where needed.</p> 824 825 <h4 id="cxx_inheriting_constructors">C++11 inheriting constructors</h4> 826 827 <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> 828 829 <h4 id="cxx_inline_namespaces">C++11 inline namespaces</h4> 830 831 <p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> or 832 <tt>__has_extension(cxx_inline_namespaces)</tt> to determine if support for 833 inline namespaces is enabled.</p> 834 835 <h4 id="cxx_lambdas">C++11 lambdas</h4> 836 837 <p>Use <tt>__has_feature(cxx_lambdas)</tt> or 838 <tt>__has_extension(cxx_lambdas)</tt> to determine if support for lambdas 839 is enabled. </p> 840 841 <h4 id="cxx_local_type_template_args">C++11 local and unnamed types as template arguments</h4> 842 843 <p>Use <tt>__has_feature(cxx_local_type_template_args)</tt> or 844 <tt>__has_extension(cxx_local_type_template_args)</tt> to determine if 845 support for local and unnamed types as template arguments is enabled.</p> 846 847 <h4 id="cxx_noexcept">C++11 noexcept</h4> 848 849 <p>Use <tt>__has_feature(cxx_noexcept)</tt> or 850 <tt>__has_extension(cxx_noexcept)</tt> to determine if support for noexcept 851 exception specifications is enabled.</p> 852 853 <h4 id="cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</h4> 854 855 <p>Use <tt>__has_feature(cxx_nonstatic_member_init)</tt> to determine whether in-class initialization of non-static data members is enabled.</p> 856 857 <h4 id="cxx_nullptr">C++11 <tt>nullptr</tt></h4> 858 859 <p>Use <tt>__has_feature(cxx_nullptr)</tt> or 860 <tt>__has_extension(cxx_nullptr)</tt> to determine if support for 861 <tt>nullptr</tt> is enabled.</p> 862 863 <h4 id="cxx_override_control">C++11 <tt>override control</tt></h4> 864 865 <p>Use <tt>__has_feature(cxx_override_control)</tt> or 866 <tt>__has_extension(cxx_override_control)</tt> to determine if support for 867 the override control keywords is enabled.</p> 868 869 <h4 id="cxx_reference_qualified_functions">C++11 reference-qualified functions</h4> 870 <p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> or 871 <tt>__has_extension(cxx_reference_qualified_functions)</tt> to determine 872 if support for reference-qualified functions (e.g., member functions with 873 <code>&</code> or <code>&&</code> applied to <code>*this</code>) 874 is enabled.</p> 875 876 <h4 id="cxx_range_for">C++11 range-based <tt>for</tt> loop</h4> 877 878 <p>Use <tt>__has_feature(cxx_range_for)</tt> or 879 <tt>__has_extension(cxx_range_for)</tt> to determine if support for the 880 range-based for loop is enabled. </p> 881 882 <h4 id="cxx_raw_string_literals">C++11 raw string literals</h4> 883 <p>Use <tt>__has_feature(cxx_raw_string_literals)</tt> to determine if support 884 for raw string literals (e.g., <tt>R"x(foo\bar)x"</tt>) is enabled.</p> 885 886 <h4 id="cxx_rvalue_references">C++11 rvalue references</h4> 887 888 <p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or 889 <tt>__has_extension(cxx_rvalue_references)</tt> to determine if support for 890 rvalue references is enabled. </p> 891 892 <h4 id="cxx_static_assert">C++11 <tt>static_assert()</tt></h4> 893 894 <p>Use <tt>__has_feature(cxx_static_assert)</tt> or 895 <tt>__has_extension(cxx_static_assert)</tt> to determine if support for 896 compile-time assertions using <tt>static_assert</tt> is enabled.</p> 897 898 <h4 id="cxx_auto_type">C++11 type inference</h4> 899 900 <p>Use <tt>__has_feature(cxx_auto_type)</tt> or 901 <tt>__has_extension(cxx_auto_type)</tt> to determine C++11 type inference is 902 supported using the <tt>auto</tt> specifier. If this is disabled, <tt>auto</tt> 903 will instead be a storage class specifier, as in C or C++98.</p> 904 905 <h4 id="cxx_strong_enums">C++11 strongly typed enumerations</h4> 906 907 <p>Use <tt>__has_feature(cxx_strong_enums)</tt> or 908 <tt>__has_extension(cxx_strong_enums)</tt> to determine if support for 909 strongly typed, scoped enumerations is enabled.</p> 910 911 <h4 id="cxx_trailing_return">C++11 trailing return type</h4> 912 913 <p>Use <tt>__has_feature(cxx_trailing_return)</tt> or 914 <tt>__has_extension(cxx_trailing_return)</tt> to determine if support for the 915 alternate function declaration syntax with trailing return type is enabled.</p> 916 917 <h4 id="cxx_unicode_literals">C++11 Unicode string literals</h4> 918 <p>Use <tt>__has_feature(cxx_unicode_literals)</tt> to determine if 919 support for Unicode string literals is enabled.</p> 920 921 <h4 id="cxx_unrestricted_unions">C++11 unrestricted unions</h4> 922 923 <p>Use <tt>__has_feature(cxx_unrestricted_unions)</tt> to determine if support for unrestricted unions is enabled.</p> 924 925 <h4 id="cxx_user_literals">C++11 user-defined literals</h4> 926 927 <p>Use <tt>__has_feature(cxx_user_literals)</tt> to determine if support for user-defined literals is enabled.</p> 928 929 <h4 id="cxx_variadic_templates">C++11 variadic templates</h4> 930 931 <p>Use <tt>__has_feature(cxx_variadic_templates)</tt> or 932 <tt>__has_extension(cxx_variadic_templates)</tt> to determine if support 933 for variadic templates is enabled.</p> 934 935 <h3 id="c11">C11</h3> 936 937 <p>The features listed below are part of the C11 standard. As a result, all 938 these features are enabled with the <tt>-std=c11</tt> or <tt>-std=gnu11</tt> 939 option when compiling C code. Additionally, because these features are all 940 backward-compatible, they are available as extensions in all language modes.</p> 941 942 <h4 id="c_alignas">C11 alignment specifiers</h4> 943 944 <p>Use <tt>__has_feature(c_alignas)</tt> or <tt>__has_extension(c_alignas)</tt> 945 to determine if support for alignment specifiers using <tt>_Alignas</tt> 946 is enabled.</p> 947 948 <h4 id="c_atomic">C11 atomic operations</h4> 949 950 <p>Use <tt>__has_feature(c_atomic)</tt> or <tt>__has_extension(c_atomic)</tt> 951 to determine if support for atomic types using <tt>_Atomic</tt> is enabled. 952 Clang also provides <a href="#__c11_atomic">a set of builtins</a> which can be 953 used to implement the <tt><stdatomic.h></tt> operations on 954 <tt>_Atomic</tt> types.</p> 955 956 <h4 id="c_generic_selections">C11 generic selections</h4> 957 958 <p>Use <tt>__has_feature(c_generic_selections)</tt> or 959 <tt>__has_extension(c_generic_selections)</tt> to determine if support for 960 generic selections is enabled.</p> 961 962 <p>As an extension, the C11 generic selection expression is available in all 963 languages supported by Clang. The syntax is the same as that given in the 964 C11 standard.</p> 965 966 <p>In C, type compatibility is decided according to the rules given in the 967 appropriate standard, but in C++, which lacks the type compatibility rules 968 used in C, types are considered compatible only if they are equivalent.</p> 969 970 <h4 id="c_static_assert">C11 <tt>_Static_assert()</tt></h4> 971 972 <p>Use <tt>__has_feature(c_static_assert)</tt> or 973 <tt>__has_extension(c_static_assert)</tt> to determine if support for 974 compile-time assertions using <tt>_Static_assert</tt> is enabled.</p> 975 976 <!-- ======================================================================= --> 977 <h2 id="checking_type_traits">Checks for Type Traits</h2> 978 <!-- ======================================================================= --> 979 980 <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: 981 <blockquote> 982 <pre> 983 #if __has_extension(is_convertible_to) 984 template<typename From, typename To> 985 struct is_convertible_to { 986 static const bool value = __is_convertible_to(From, To); 987 }; 988 #else 989 // Emulate type trait 990 #endif 991 </pre> 992 </blockquote> 993 994 <p>The following type traits are supported by Clang:</p> 995 <ul> 996 <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li> 997 <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li> 998 <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li> 999 <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li> 1000 <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li> 1001 <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li> 1002 <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li> 1003 <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li> 1004 <li><code>__is_abstract</code> (GNU, Microsoft)</li> 1005 <li><code>__is_base_of</code> (GNU, Microsoft)</li> 1006 <li><code>__is_class</code> (GNU, Microsoft)</li> 1007 <li><code>__is_convertible_to</code> (Microsoft)</li> 1008 <li><code>__is_empty</code> (GNU, Microsoft)</li> 1009 <li><code>__is_enum</code> (GNU, Microsoft)</li> 1010 <li><code>__is_pod</code> (GNU, Microsoft)</li> 1011 <li><code>__is_polymorphic</code> (GNU, Microsoft)</li> 1012 <li><code>__is_union</code> (GNU, Microsoft)</li> 1013 <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li> 1014 <li><code>__is_final</code>: Determines whether the given type is declared with a <code>final</code> class-virt-specifier.</li> 1015 <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> 1016 <li><code>__is_trivially_assignable(totype, fromtype)</code>: Determines whether a value of type <tt>totype</tt> can be assigned to from a value of type <tt>fromtype</tt> such that no non-trivial functions are called as part of that assignment. This trait is required to implement the C++11 standard library.</li> 1017 <li><code>__is_trivially_constructible(type, argtypes...)</code>: Determines whether a value of type <tt>type</tt> can be direct-initialized with arguments of types <tt>argtypes...</tt> such that no non-trivial functions are called as part of that initialization. This trait is required to implement the C++11 standard library.</li> 1018 </ul> 1019 1020 <!-- ======================================================================= --> 1021 <h2 id="blocks">Blocks</h2> 1022 <!-- ======================================================================= --> 1023 1024 <p>The syntax and high level language feature description is in <a 1025 href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI 1026 details for the clang implementation are in <a 1027 href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p> 1028 1029 1030 <p>Query for this feature with __has_extension(blocks).</p> 1031 1032 <!-- ======================================================================= --> 1033 <h2 id="objc_features">Objective-C Features</h2> 1034 <!-- ======================================================================= --> 1035 1036 <h3 id="objc_instancetype">Related result types</h3> 1037 1038 <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> 1039 1040 <blockquote> 1041 <pre> 1042 @interface NSObject 1043 + (id)alloc; 1044 - (id)init; 1045 @end 1046 1047 @interface NSArray : NSObject 1048 @end 1049 </pre> 1050 </blockquote> 1051 1052 <p>and this common initialization pattern</p> 1053 1054 <blockquote> 1055 <pre> 1056 NSArray *array = [[NSArray alloc] init]; 1057 </pre> 1058 </blockquote> 1059 1060 <p>the type of the expression <code>[NSArray alloc]</code> is 1061 <code>NSArray*</code> because <code>alloc</code> implicitly has a 1062 related result type. Similarly, the type of the expression 1063 <code>[[NSArray alloc] init]</code> is <code>NSArray*</code>, since 1064 <code>init</code> has a related result type and its receiver is known 1065 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> 1066 1067 <p>A method with a related result type can be declared by using the 1068 type <tt>instancetype</tt> as its result type. <tt>instancetype</tt> 1069 is a contextual keyword that is only permitted in the result type of 1070 an Objective-C method, e.g.</p> 1071 1072 <pre> 1073 @interface A 1074 + (<b>instancetype</b>)constructAnA; 1075 @end 1076 </pre> 1077 1078 <p>The related result type can also be inferred for some methods. 1079 To determine whether a method has an inferred related result type, the first 1080 word in the camel-case selector (e.g., "init" in "initWithObjects") is 1081 considered, and the method will have a related result type if its return 1082 type is compatible with the type of its class and if</p> 1083 1084 <ul> 1085 1086 <li>the first word is "alloc" or "new", and the method is a class 1087 method, or</li> 1088 1089 <li>the first word is "autorelease", "init", "retain", or "self", 1090 and the method is an instance method.</li> 1091 1092 </ul> 1093 1094 <p>If a method with a related result type is overridden by a subclass 1095 method, the subclass method must also return a type that is compatible 1096 with the subclass type. For example:</p> 1097 1098 <blockquote> 1099 <pre> 1100 @interface NSString : NSObject 1101 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString 1102 @end 1103 </pre> 1104 </blockquote> 1105 1106 <p>Related result types only affect the type of a message send or 1107 property access via the given method. In all other respects, a method 1108 with a related result type is treated the same way as method that 1109 returns <tt>id</tt>.</p> 1110 1111 <p>Use <tt>__has_feature(objc_instancetype)</tt> to determine whether 1112 the <tt>instancetype</tt> contextual keyword is available.</p> 1113 1114 <!-- ======================================================================= --> 1115 <h2 id="objc_arc">Automatic reference counting </h2> 1116 <!-- ======================================================================= --> 1117 1118 <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> 1119 1120 <!-- ======================================================================= --> 1121 <h2 id="objc_fixed_enum">Enumerations with a fixed underlying type</h2> 1122 <!-- ======================================================================= --> 1123 1124 <p>Clang provides support for C++11 enumerations with a fixed 1125 underlying type within Objective-C. For example, one can write an 1126 enumeration type as:</p> 1127 1128 <pre> 1129 typedef enum : unsigned char { Red, Green, Blue } Color; 1130 </pre> 1131 1132 <p>This specifies that the underlying type, which is used to store the 1133 enumeration value, is <tt>unsigned char</tt>.</p> 1134 1135 <p>Use <tt>__has_feature(objc_fixed_enum)</tt> to determine whether 1136 support for fixed underlying types is available in Objective-C.</p> 1137 1138 <!-- ======================================================================= --> 1139 <h2 id="objc_lambdas">Interoperability with C++11 lambdas</h2> 1140 <!-- ======================================================================= --> 1141 1142 <p>Clang provides interoperability between C++11 lambdas and 1143 blocks-based APIs, by permitting a lambda to be implicitly converted 1144 to a block pointer with the corresponding signature. For example, 1145 consider an API such as <code>NSArray</code>'s array-sorting 1146 method:</p> 1147 1148 <pre> - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr; </pre> 1149 1150 <p><code>NSComparator</code> is simply a typedef for the block pointer 1151 <code>NSComparisonResult (^)(id, id)</code>, and parameters of this 1152 type are generally provided with block literals as arguments. However, 1153 one can also use a C++11 lambda so long as it provides the same 1154 signature (in this case, accepting two parameters of type 1155 <code>id</code> and returning an <code>NSComparisonResult</code>):</p> 1156 1157 <pre> 1158 NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11", 1159 @"String 02"]; 1160 const NSStringCompareOptions comparisonOptions 1161 = NSCaseInsensitiveSearch | NSNumericSearch | 1162 NSWidthInsensitiveSearch | NSForcedOrderingSearch; 1163 NSLocale *currentLocale = [NSLocale currentLocale]; 1164 NSArray *sorted 1165 = [array sortedArrayUsingComparator:<b>[=](id s1, id s2) -> NSComparisonResult { 1166 NSRange string1Range = NSMakeRange(0, [s1 length]); 1167 return [s1 compare:s2 options:comparisonOptions 1168 range:string1Range locale:currentLocale]; 1169 }</b>]; 1170 NSLog(@"sorted: %@", sorted); 1171 </pre> 1172 1173 <p>This code relies on an implicit conversion from the type of the 1174 lambda expression (an unnamed, local class type called the <i>closure 1175 type</i>) to the corresponding block pointer type. The conversion 1176 itself is expressed by a conversion operator in that closure type 1177 that produces a block pointer with the same signature as the lambda 1178 itself, e.g.,</p> 1179 1180 <pre> 1181 operator NSComparisonResult (^)(id, id)() const; 1182 </pre> 1183 1184 <p>This conversion function returns a new block that simply forwards 1185 the two parameters to the lambda object (which it captures by copy), 1186 then returns the result. The returned block is first copied (with 1187 <tt>Block_copy</tt>) and then autoreleased. As an optimization, if a 1188 lambda expression is immediately converted to a block pointer (as in 1189 the first example, above), then the block is not copied and 1190 autoreleased: rather, it is given the same lifetime as a block literal 1191 written at that point in the program, which avoids the overhead of 1192 copying a block to the heap in the common case.</p> 1193 1194 <p>The conversion from a lambda to a block pointer is only available 1195 in Objective-C++, and not in C++ with blocks, due to its use of 1196 Objective-C memory management (autorelease).</p> 1197 1198 <!-- ======================================================================= --> 1199 <h2 id="objc_object_literals_subscripting">Object Literals and Subscripting</h2> 1200 <!-- ======================================================================= --> 1201 1202 <p>Clang provides support for <a href="ObjectiveCLiterals.html">Object Literals 1203 and Subscripting</a> in Objective-C, which simplifies common Objective-C 1204 programming patterns, makes programs more concise, and improves the safety of 1205 container creation. There are several feature macros associated with object 1206 literals and subscripting: <code>__has_feature(objc_array_literals)</code> 1207 tests the availability of array literals; 1208 <code>__has_feature(objc_dictionary_literals)</code> tests the availability of 1209 dictionary literals; <code>__has_feature(objc_subscripting)</code> tests the 1210 availability of object subscripting.</p> 1211 1212 <!-- ======================================================================= --> 1213 <h2 id="objc_default_synthesize_properties">Objective-C Autosynthesis of Properties</h2> 1214 <!-- ======================================================================= --> 1215 1216 <p> Clang provides support for autosynthesis of declared properties. Using this 1217 feature, clang provides default synthesis of those properties not declared @dynamic 1218 and not having user provided backing getter and setter methods. 1219 <code>__has_feature(objc_default_synthesize_properties)</code> checks for availability 1220 of this feature in version of clang being used.</p> 1221 1222 <!-- ======================================================================= --> 1223 <h2 id="overloading-in-c">Function Overloading in C</h2> 1224 <!-- ======================================================================= --> 1225 1226 <p>Clang provides support for C++ function overloading in C. Function 1227 overloading in C is introduced using the <tt>overloadable</tt> attribute. For 1228 example, one might provide several overloaded versions of a <tt>tgsin</tt> 1229 function that invokes the appropriate standard function computing the sine of a 1230 value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt> 1231 precision:</p> 1232 1233 <blockquote> 1234 <pre> 1235 #include <math.h> 1236 float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); } 1237 double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); } 1238 long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); } 1239 </pre> 1240 </blockquote> 1241 1242 <p>Given these declarations, one can call <tt>tgsin</tt> with a 1243 <tt>float</tt> value to receive a <tt>float</tt> result, with a 1244 <tt>double</tt> to receive a <tt>double</tt> result, etc. Function 1245 overloading in C follows the rules of C++ function overloading to pick 1246 the best overload given the call arguments, with a few C-specific 1247 semantics:</p> 1248 <ul> 1249 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long 1250 double</tt> is ranked as a floating-point promotion (per C99) rather 1251 than as a floating-point conversion (as in C++).</li> 1252 1253 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type 1254 <tt>U*</tt> is considered a pointer conversion (with conversion 1255 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li> 1256 1257 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt> 1258 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This 1259 conversion is given "conversion" rank.</li> 1260 </ul> 1261 1262 <p>The declaration of <tt>overloadable</tt> functions is restricted to 1263 function declarations and definitions. Most importantly, if any 1264 function with a given name is given the <tt>overloadable</tt> 1265 attribute, then all function declarations and definitions with that 1266 name (and in that scope) must have the <tt>overloadable</tt> 1267 attribute. This rule even applies to redeclarations of functions whose original 1268 declaration had the <tt>overloadable</tt> attribute, e.g.,</p> 1269 1270 <blockquote> 1271 <pre> 1272 int f(int) __attribute__((overloadable)); 1273 float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i> 1274 1275 int g(int) __attribute__((overloadable)); 1276 int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i> 1277 </pre> 1278 </blockquote> 1279 1280 <p>Functions marked <tt>overloadable</tt> must have 1281 prototypes. Therefore, the following code is ill-formed:</p> 1282 1283 <blockquote> 1284 <pre> 1285 int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i> 1286 </pre> 1287 </blockquote> 1288 1289 <p>However, <tt>overloadable</tt> functions are allowed to use a 1290 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> 1291 1292 <blockquote> 1293 <pre> 1294 void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i> 1295 </pre> 1296 </blockquote> 1297 1298 <p>Functions declared with the <tt>overloadable</tt> attribute have 1299 their names mangled according to the same rules as C++ function 1300 names. For example, the three <tt>tgsin</tt> functions in our 1301 motivating example get the mangled names <tt>_Z5tgsinf</tt>, 1302 <tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two 1303 caveats to this use of name mangling:</p> 1304 1305 <ul> 1306 1307 <li>Future versions of Clang may change the name mangling of 1308 functions overloaded in C, so you should not depend on an specific 1309 mangling. To be completely safe, we strongly urge the use of 1310 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li> 1311 1312 <li>The <tt>overloadable</tt> attribute has almost no meaning when 1313 used in C++, because names will already be mangled and functions are 1314 already overloadable. However, when an <tt>overloadable</tt> 1315 function occurs within an <tt>extern "C"</tt> linkage specification, 1316 it's name <i>will</i> be mangled in the same way as it would in 1317 C.</li> 1318 </ul> 1319 1320 <p>Query for this feature with __has_extension(attribute_overloadable).</p> 1321 1322 <!-- ======================================================================= --> 1323 <h2 id="complex-list-init">Initializer lists for complex numbers in C</h2> 1324 <!-- ======================================================================= --> 1325 1326 <p>clang supports an extension which allows the following in C:</p> 1327 1328 <blockquote> 1329 <pre> 1330 #include <math.h> 1331 #include <complex.h> 1332 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf) 1333 </pre> 1334 </blockquote> 1335 1336 <p>This construct is useful because there is no way to separately 1337 initialize the real and imaginary parts of a complex variable in 1338 standard C, given that clang does not support <code>_Imaginary</code>. 1339 (clang also supports the <code>__real__</code> and <code>__imag__</code> 1340 extensions from gcc, which help in some cases, but are not usable in 1341 static initializers.) 1342 1343 <p>Note that this extension does not allow eliding the braces; the 1344 meaning of the following two lines is different:</p> 1345 1346 <blockquote> 1347 <pre> 1348 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1) 1349 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0) 1350 </pre> 1351 </blockquote> 1352 1353 <p>This extension also works in C++ mode, as far as that goes, but does not 1354 apply to the C++ <code>std::complex</code>. (In C++11, list 1355 initialization allows the same syntax to be used with 1356 <code>std::complex</code> with the same meaning.) 1357 1358 <!-- ======================================================================= --> 1359 <h2 id="builtins">Builtin Functions</h2> 1360 <!-- ======================================================================= --> 1361 1362 <p>Clang supports a number of builtin library functions with the same syntax as 1363 GCC, including things like <tt>__builtin_nan</tt>, 1364 <tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>, 1365 <tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In 1366 addition to the GCC builtins, Clang supports a number of builtins that GCC does 1367 not, which are listed here.</p> 1368 1369 <p>Please note that Clang does not and will not support all of the GCC builtins 1370 for vector operations. Instead of using builtins, you should use the functions 1371 defined in target-specific header files like <tt><xmmintrin.h></tt>, which 1372 define portable wrappers for these. Many of the Clang versions of these 1373 functions are implemented directly in terms of <a href="#vectors">extended 1374 vector support</a> instead of builtins, in order to reduce the number of 1375 builtins that we need to implement.</p> 1376 1377 <!-- ======================================================================= --> 1378 <h3><a name="__builtin_readcyclecounter">__builtin_readcyclecounter</a></h3> 1379 <!-- ======================================================================= --> 1380 1381 <p><tt>__builtin_readcyclecounter</tt> is used to access the cycle counter 1382 register (or a similar low-latency, high-accuracy clock) on those targets that 1383 support it. 1384 </p> 1385 1386 <p><b>Syntax:</b></p> 1387 1388 <pre> 1389 __builtin_readcyclecounter() 1390 </pre> 1391 1392 <p><b>Example of Use:</b></p> 1393 1394 <pre> 1395 unsigned long long t0 = __builtin_readcyclecounter(); 1396 do_something(); 1397 unsigned long long t1 = __builtin_readcyclecounter(); 1398 unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow 1399 </pre> 1400 1401 <p><b>Description:</b></p> 1402 1403 <p>The __builtin_readcyclecounter() builtin returns the cycle counter value, 1404 which may be either global or process/thread-specific depending on the target. 1405 As the backing counters often overflow quickly (on the order of 1406 seconds) this should only be used for timing small intervals. When not 1407 supported by the target, the return value is always zero. This builtin 1408 takes no arguments and produces an unsigned long long result. 1409 </p> 1410 1411 <p>Query for this feature with __has_builtin(__builtin_readcyclecounter).</p> 1412 1413 <!-- ======================================================================= --> 1414 <h3><a name="__builtin_shufflevector">__builtin_shufflevector</a></h3> 1415 <!-- ======================================================================= --> 1416 1417 <p><tt>__builtin_shufflevector</tt> is used to express generic vector 1418 permutation/shuffle/swizzle operations. This builtin is also very important for 1419 the implementation of various target-specific header files like 1420 <tt><xmmintrin.h></tt>. 1421 </p> 1422 1423 <p><b>Syntax:</b></p> 1424 1425 <pre> 1426 __builtin_shufflevector(vec1, vec2, index1, index2, ...) 1427 </pre> 1428 1429 <p><b>Examples:</b></p> 1430 1431 <pre> 1432 // Identity operation - return 4-element vector V1. 1433 __builtin_shufflevector(V1, V1, 0, 1, 2, 3) 1434 1435 // "Splat" element 0 of V1 into a 4-element result. 1436 __builtin_shufflevector(V1, V1, 0, 0, 0, 0) 1437 1438 // Reverse 4-element vector V1. 1439 __builtin_shufflevector(V1, V1, 3, 2, 1, 0) 1440 1441 // Concatenate every other element of 4-element vectors V1 and V2. 1442 __builtin_shufflevector(V1, V2, 0, 2, 4, 6) 1443 1444 // Concatenate every other element of 8-element vectors V1 and V2. 1445 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14) 1446 </pre> 1447 1448 <p><b>Description:</b></p> 1449 1450 <p>The first two arguments to __builtin_shufflevector are vectors that have the 1451 same element type. The remaining arguments are a list of integers that specify 1452 the elements indices of the first two vectors that should be extracted and 1453 returned in a new vector. These element indices are numbered sequentially 1454 starting with the first vector, continuing into the second vector. Thus, if 1455 vec1 is a 4-element vector, index 5 would refer to the second element of vec2. 1456 </p> 1457 1458 <p>The result of __builtin_shufflevector is a vector 1459 with the same element type as vec1/vec2 but that has an element count equal to 1460 the number of indices specified. 1461 </p> 1462 1463 <p>Query for this feature with __has_builtin(__builtin_shufflevector).</p> 1464 1465 <!-- ======================================================================= --> 1466 <h3><a name="__builtin_unreachable">__builtin_unreachable</a></h3> 1467 <!-- ======================================================================= --> 1468 1469 <p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in 1470 the program cannot be reached, even if the compiler might otherwise think it 1471 can. This is useful to improve optimization and eliminates certain warnings. 1472 For example, without the <tt>__builtin_unreachable</tt> in the example below, 1473 the compiler assumes that the inline asm can fall through and prints a "function 1474 declared 'noreturn' should not return" warning. 1475 </p> 1476 1477 <p><b>Syntax:</b></p> 1478 1479 <pre> 1480 __builtin_unreachable() 1481 </pre> 1482 1483 <p><b>Example of Use:</b></p> 1484 1485 <pre> 1486 void myabort(void) __attribute__((noreturn)); 1487 void myabort(void) { 1488 asm("int3"); 1489 __builtin_unreachable(); 1490 } 1491 </pre> 1492 1493 <p><b>Description:</b></p> 1494 1495 <p>The __builtin_unreachable() builtin has completely undefined behavior. Since 1496 it has undefined behavior, it is a statement that it is never reached and the 1497 optimizer can take advantage of this to produce better code. This builtin takes 1498 no arguments and produces a void result. 1499 </p> 1500 1501 <p>Query for this feature with __has_builtin(__builtin_unreachable).</p> 1502 1503 <!-- ======================================================================= --> 1504 <h3><a name="__sync_swap">__sync_swap</a></h3> 1505 <!-- ======================================================================= --> 1506 1507 <p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in 1508 memory. 1509 </p> 1510 1511 <p><b>Syntax:</b></p> 1512 1513 <pre> 1514 <i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...) 1515 </pre> 1516 1517 <p><b>Example of Use:</b></p> 1518 1519 <pre> 1520 int old_value = __sync_swap(&value, new_value); 1521 </pre> 1522 1523 <p><b>Description:</b></p> 1524 1525 <p>The __sync_swap() builtin extends the existing __sync_*() family of atomic 1526 intrinsics to allow code to atomically swap the current value with the new 1527 value. More importantly, it helps developers write more efficient and correct 1528 code by avoiding expensive loops around __sync_bool_compare_and_swap() or 1529 relying on the platform specific implementation details of 1530 __sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier. 1531 </p> 1532 1533 <!-- ======================================================================= --> 1534 <h3><a name="__c11_atomic">__c11_atomic builtins</a></h3> 1535 <!-- ======================================================================= --> 1536 1537 <p>Clang provides a set of builtins which are intended to be used to implement 1538 C11's <tt><stdatomic.h></tt> header. These builtins provide the semantics 1539 of the <tt>_explicit</tt> form of the corresponding C11 operation, and are named 1540 with a <tt>__c11_</tt> prefix. The supported operations are:</p> 1541 1542 <ul> 1543 <li><tt>__c11_atomic_init</tt></li> 1544 <li><tt>__c11_atomic_thread_fence</tt></li> 1545 <li><tt>__c11_atomic_signal_fence</tt></li> 1546 <li><tt>__c11_atomic_is_lock_free</tt></li> 1547 <li><tt>__c11_atomic_store</tt></li> 1548 <li><tt>__c11_atomic_load</tt></li> 1549 <li><tt>__c11_atomic_exchange</tt></li> 1550 <li><tt>__c11_atomic_compare_exchange_strong</tt></li> 1551 <li><tt>__c11_atomic_compare_exchange_weak</tt></li> 1552 <li><tt>__c11_atomic_fetch_add</tt></li> 1553 <li><tt>__c11_atomic_fetch_sub</tt></li> 1554 <li><tt>__c11_atomic_fetch_and</tt></li> 1555 <li><tt>__c11_atomic_fetch_or</tt></li> 1556 <li><tt>__c11_atomic_fetch_xor</tt></li> 1557 </ul> 1558 1559 <!-- ======================================================================= --> 1560 <h2 id="non-standard-attributes">Non-standard C++11 Attributes</h2> 1561 <!-- ======================================================================= --> 1562 1563 <p>Clang supports one non-standard C++11 attribute. It resides in the 1564 <tt>clang</tt> attribute namespace.</p> 1565 1566 <!-- ======================================================================= --> 1567 <h3 id="clang__fallthrough">The <tt>clang::fallthrough</tt> attribute</h3> 1568 <!-- ======================================================================= --> 1569 1570 <p>The <tt>clang::fallthrough</tt> attribute is used along with the 1571 <tt>-Wimplicit-fallthrough</tt> argument to annotate intentional fall-through 1572 between switch labels. It can only be applied to a null statement placed at a 1573 point of execution between any statement and the next switch label. It is common 1574 to mark these places with a specific comment, but this attribute is meant to 1575 replace comments with a more strict annotation, which can be checked by the 1576 compiler. This attribute doesn't change semantics of the code and can be used 1577 wherever an intended fall-through occurs. It is designed to mimic 1578 control-flow statements like <tt>break;</tt>, so it can be placed in most places 1579 where <tt>break;</tt> can, but only if there are no statements on the execution 1580 path between it and the next switch label.</p> 1581 <p>Here is an example:</p> 1582 <pre> 1583 // compile with -Wimplicit-fallthrough 1584 switch (n) { 1585 case 33: 1586 f(); 1587 case 44: // warning: unannotated fall-through 1588 g(); 1589 <b>[[clang::fallthrough]];</b> 1590 case 55: // no warning 1591 if (x) { 1592 h(); 1593 break; 1594 } 1595 else { 1596 i(); 1597 <b>[[clang::fallthrough]];</b> 1598 } 1599 case 66: // no warning 1600 p(); 1601 <b>[[clang::fallthrough]];</b> // warning: fallthrough annotation does not directly precede case label 1602 q(); 1603 case 77: // warning: unannotated fall-through 1604 r(); 1605 } 1606 </pre> 1607 1608 <!-- ======================================================================= --> 1609 <h2 id="targetspecific">Target-Specific Extensions</h2> 1610 <!-- ======================================================================= --> 1611 1612 <p>Clang supports some language features conditionally on some targets.</p> 1613 1614 <!-- ======================================================================= --> 1615 <h3 id="x86-specific">X86/X86-64 Language Extensions</h3> 1616 <!-- ======================================================================= --> 1617 1618 <p>The X86 backend has these language extensions:</p> 1619 1620 <!-- ======================================================================= --> 1621 <h4 id="x86-gs-segment">Memory references off the GS segment</h4> 1622 <!-- ======================================================================= --> 1623 1624 <p>Annotating a pointer with address space #256 causes it to be code generated 1625 relative to the X86 GS segment register, and address space #257 causes it to be 1626 relative to the X86 FS segment. Note that this is a very very low-level 1627 feature that should only be used if you know what you're doing (for example in 1628 an OS kernel).</p> 1629 1630 <p>Here is an example:</p> 1631 1632 <pre> 1633 #define GS_RELATIVE __attribute__((address_space(256))) 1634 int foo(int GS_RELATIVE *P) { 1635 return *P; 1636 } 1637 </pre> 1638 1639 <p>Which compiles to (on X86-32):</p> 1640 1641 <pre> 1642 _foo: 1643 movl 4(%esp), %eax 1644 movl %gs:(%eax), %eax 1645 ret 1646 </pre> 1647 1648 <!-- ======================================================================= --> 1649 <h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2> 1650 <!-- ======================================================================= --> 1651 1652 <p>Clang supports additional attributes that are useful for documenting program 1653 invariants and rules for static analysis tools. The extensions documented here 1654 are used by the <a 1655 href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer 1656 engine</a> that is part of Clang's Analysis library.</p> 1657 1658 <h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3> 1659 1660 <p>Clang's static analysis engine understands the standard <tt>noreturn</tt> 1661 attribute. This attribute, which is typically affixed to a function prototype, 1662 indicates that a call to a given function never returns. Function prototypes for 1663 common functions like <tt>exit</tt> are typically annotated with this attribute, 1664 as well as a variety of common assertion handlers. Users can educate the static 1665 analyzer about their own custom assertion handles (thus cutting down on false 1666 positives due to false paths) by marking their own "panic" functions 1667 with this attribute.</p> 1668 1669 <p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes 1670 there are special functions that for all intents and purposes should be 1671 considered panic functions (i.e., they are only called when an internal program 1672 error occurs) but may actually return so that the program can fail gracefully. 1673 The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions 1674 as being interpreted as "no return" functions by the analyzer (thus 1675 pruning bogus paths) but will not affect compilation (as in the case of 1676 <tt>noreturn</tt>).</p> 1677 1678 <p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the 1679 same places where the <tt>noreturn</tt> attribute can be placed. It is commonly 1680 placed at the end of function prototypes:</p> 1681 1682 <pre> 1683 void foo() <b>__attribute__((analyzer_noreturn))</b>; 1684 </pre> 1685 1686 <p>Query for this feature with 1687 <tt>__has_attribute(analyzer_noreturn)</tt>.</p> 1688 1689 <h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3> 1690 1691 <p>Many methods in Objective-C have conventional meanings determined 1692 by their selectors. For the purposes of static analysis, it is 1693 sometimes useful to be able to mark a method as having a particular 1694 conventional meaning despite not having the right selector, or as not 1695 having the conventional meaning that its selector would suggest. 1696 For these use cases, we provide an attribute to specifically describe 1697 the <q>method family</q> that a method belongs to.</p> 1698 1699 <p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>, 1700 where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>, 1701 <tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>. This attribute 1702 can only be placed at the end of a method declaration:</p> 1703 1704 <pre> 1705 - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>; 1706 </pre> 1707 1708 <p>Users who do not wish to change the conventional meaning of a 1709 method, and who merely want to document its non-standard retain and 1710 release semantics, should use the 1711 <a href="#attr_retain_release">retaining behavior attributes</a> 1712 described below.</p> 1713 1714 <p>Query for this feature with 1715 <tt>__has_attribute(objc_method_family)</tt>.</p> 1716 1717 <h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3> 1718 1719 <p>In Objective-C, functions and methods are generally assumed to take 1720 and return objects with +0 retain counts, with some exceptions for 1721 special methods like <tt>+alloc</tt> and <tt>init</tt>. However, 1722 there are exceptions, and so Clang provides attributes to allow these 1723 exceptions to be documented, which helps the analyzer find leaks (and 1724 ignore non-leaks). Some exceptions may be better described using 1725 the <a href="#attr_method_family"><tt>objc_method_family</tt></a> 1726 attribute instead.</p> 1727 1728 <p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>, 1729 <tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>, 1730 and <tt>cf_returns_not_retained</tt> attributes can be placed on 1731 methods and functions that return Objective-C or CoreFoundation 1732 objects. They are commonly placed at the end of a function prototype 1733 or method declaration:</p> 1734 1735 <pre> 1736 id foo() <b>__attribute__((ns_returns_retained))</b>; 1737 1738 - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>; 1739 </pre> 1740 1741 <p>The <tt>*_returns_retained</tt> attributes specify that the 1742 returned object has a +1 retain count. 1743 The <tt>*_returns_not_retained</tt> attributes specify that the return 1744 object has a +0 retain count, even if the normal convention for its 1745 selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the 1746 returned object is +0, but is guaranteed to live at least as long as the 1747 next flush of an autorelease pool.</p> 1748 1749 <p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt> 1750 attributes can be placed on an parameter declaration; they specify 1751 that the argument is expected to have a +1 retain count, which will be 1752 balanced in some way by the function or method. 1753 The <tt>ns_consumes_self</tt> attribute can only be placed on an 1754 Objective-C method; it specifies that the method expects 1755 its <tt>self</tt> parameter to have a +1 retain count, which it will 1756 balance in some way.</p> 1757 1758 <pre> 1759 void <b>foo(__attribute__((ns_consumed))</b> NSString *string); 1760 1761 - (void) bar <b>__attribute__((ns_consumes_self))</b>; 1762 - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x; 1763 </pre> 1764 1765 <p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>, 1766 <tt>__has_attribute(ns_returns_retained)</tt>, etc.</p> 1767 1768 <!-- ======================================================================= --> 1769 <h2 id="dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</h2> 1770 <!-- ======================================================================= --> 1771 <h3 id="address_sanitizer">AddressSanitizer</h3> 1772 <p> Use <code>__has_feature(address_sanitizer)</code> 1773 to check if the code is being built with <a 1774 href="AddressSanitizer.html">AddressSanitizer</a>. 1775 </p> 1776 <p>Use <tt>__attribute__((no_address_safety_analysis))</tt> on a function 1777 declaration to specify that address safety instrumentation (e.g. 1778 AddressSanitizer) should not be applied to that function. 1779 </p> 1780 1781 <!-- ======================================================================= --> 1782 <h2 id="threadsafety">Thread-Safety Annotation Checking</h2> 1783 <!-- ======================================================================= --> 1784 1785 <p>Clang supports additional attributes for checking basic locking policies in 1786 multithreaded programs. 1787 Clang currently parses the following list of attributes, although 1788 <b>the implementation for these annotations is currently in development.</b> 1789 For more details, see the 1790 <a href="http://gcc.gnu.org/wiki/ThreadSafetyAnnotation">GCC implementation</a>. 1791 </p> 1792 1793 <h4 id="ts_noanal">no_thread_safety_analysis</h4> 1794 1795 <p>Use <tt>__attribute__((no_thread_safety_analysis))</tt> on a function 1796 declaration to specify that the thread safety analysis should not be run on that 1797 function. This attribute provides an escape hatch (e.g. for situations when it 1798 is difficult to annotate the locking policy). </p> 1799 1800 <h4 id="ts_lockable">lockable</h4> 1801 1802 <p>Use <tt>__attribute__((lockable))</tt> on a class definition to specify 1803 that it has a lockable type (e.g. a Mutex class). This annotation is primarily 1804 used to check consistency.</p> 1805 1806 <h4 id="ts_scopedlockable">scoped_lockable</h4> 1807 1808 <p>Use <tt>__attribute__((scoped_lockable))</tt> on a class definition to 1809 specify that it has a "scoped" lockable type. Objects of this type will acquire 1810 the lock upon construction and release it upon going out of scope. 1811 This annotation is primarily used to check 1812 consistency.</p> 1813 1814 <h4 id="ts_guardedvar">guarded_var</h4> 1815 1816 <p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to 1817 specify that the variable must be accessed while holding some lock.</p> 1818 1819 <h4 id="ts_ptguardedvar">pt_guarded_var</h4> 1820 1821 <p>Use <tt>__attribute__((pt_guarded_var))</tt> on a pointer declaration to 1822 specify that the pointer must be dereferenced while holding some lock.</p> 1823 1824 <h4 id="ts_guardedby">guarded_by(l)</h4> 1825 1826 <p>Use <tt>__attribute__((guarded_by(l)))</tt> on a variable declaration to 1827 specify that the variable must be accessed while holding lock <tt>l</tt>.</p> 1828 1829 <h4 id="ts_ptguardedby">pt_guarded_by(l)</h4> 1830 1831 <p>Use <tt>__attribute__((pt_guarded_by(l)))</tt> on a pointer declaration to 1832 specify that the pointer must be dereferenced while holding lock <tt>l</tt>.</p> 1833 1834 <h4 id="ts_acquiredbefore">acquired_before(...)</h4> 1835 1836 <p>Use <tt>__attribute__((acquired_before(...)))</tt> on a declaration 1837 of a lockable variable to specify that the lock must be acquired before all 1838 attribute arguments. Arguments must be lockable type, and there must be at 1839 least one argument.</p> 1840 1841 <h4 id="ts_acquiredafter">acquired_after(...)</h4> 1842 1843 <p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration 1844 of a lockable variable to specify that the lock must be acquired after all 1845 attribute arguments. Arguments must be lockable type, and there must be at 1846 least one argument.</p> 1847 1848 <h4 id="ts_elf">exclusive_lock_function(...)</h4> 1849 1850 <p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function 1851 declaration to specify that the function acquires all listed locks 1852 exclusively. This attribute takes zero or more arguments: either of lockable 1853 type or integers indexing into function parameters of lockable type. If no 1854 arguments are given, the acquired lock is implicitly <tt>this</tt> of the 1855 enclosing object.</p> 1856 1857 <h4 id="ts_slf">shared_lock_function(...)</h4> 1858 1859 <p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function 1860 declaration to specify that the function acquires all listed locks, although 1861 the locks may be shared (e.g. read locks). This attribute takes zero or more 1862 arguments: either of lockable type or integers indexing into function 1863 parameters of lockable type. If no arguments are given, the acquired lock is 1864 implicitly <tt>this</tt> of the enclosing object.</p> 1865 1866 <h4 id="ts_etf">exclusive_trylock_function(...)</h4> 1867 1868 <p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function 1869 declaration to specify that the function will try (without blocking) to acquire 1870 all listed locks exclusively. This attribute takes one or more arguments. The 1871 first argument is an integer or boolean value specifying the return value of a 1872 successful lock acquisition. The remaining arugments are either of lockable type 1873 or integers indexing into function parameters of lockable type. If only one 1874 argument is given, the acquired lock is implicitly <tt>this</tt> of the 1875 enclosing object.</p> 1876 1877 <h4 id="ts_stf">shared_trylock_function(...)</h4> 1878 1879 <p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function 1880 declaration to specify that the function will try (without blocking) to acquire 1881 all listed locks, although the locks may be shared (e.g. read locks). This 1882 attribute takes one or more arguments. The first argument is an integer or 1883 boolean value specifying the return value of a successful lock acquisition. The 1884 remaining arugments are either of lockable type or integers indexing into 1885 function parameters of lockable type. If only one argument is given, the 1886 acquired lock is implicitly <tt>this</tt> of the enclosing object.</p> 1887 1888 <h4 id="ts_uf">unlock_function(...)</h4> 1889 1890 <p>Use <tt>__attribute__((unlock_function(...)))</tt> on a function 1891 declaration to specify that the function release all listed locks. This 1892 attribute takes zero or more arguments: either of lockable type or integers 1893 indexing into function parameters of lockable type. If no arguments are given, 1894 the acquired lock is implicitly <tt>this</tt> of the enclosing object.</p> 1895 1896 <h4 id="ts_lr">lock_returned(l)</h4> 1897 1898 <p>Use <tt>__attribute__((lock_returned(l)))</tt> on a function 1899 declaration to specify that the function returns lock <tt>l</tt> (<tt>l</tt> 1900 must be of lockable type). This annotation is used to aid in resolving lock 1901 expressions.</p> 1902 1903 <h4 id="ts_le">locks_excluded(...)</h4> 1904 1905 <p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration 1906 to specify that the function must not be called with the listed locks. Arguments 1907 must be lockable type, and there must be at least one argument.</p> 1908 1909 <h4 id="ts_elr">exclusive_locks_required(...)</h4> 1910 1911 <p>Use <tt>__attribute__((exclusive_locks_required(...)))</tt> on a function 1912 declaration to specify that the function must be called while holding the listed 1913 exclusive locks. Arguments must be lockable type, and there must be at 1914 least one argument.</p> 1915 1916 <h4 id="ts_slr">shared_locks_required(...)</h4> 1917 1918 <p>Use <tt>__attribute__((shared_locks_required(...)))</tt> on a function 1919 declaration to specify that the function must be called while holding the listed 1920 shared locks. Arguments must be lockable type, and there must be at 1921 least one argument.</p> 1922 1923 <!-- ======================================================================= --> 1924 <h2 id="type_safety">Type Safety Checking</h2> 1925 <!-- ======================================================================= --> 1926 1927 <p>Clang supports additional attributes to enable checking type safety 1928 properties that can't be enforced by C type system. Usecases include:</p> 1929 <ul> 1930 <li>MPI library implementations, where these attributes enable checking that 1931 buffer type matches the passed <tt>MPI_Datatype</tt>;</li> 1932 <li>for HDF5 library there is a similar usecase as MPI;</li> 1933 <li>checking types of variadic functions' arguments for functions like 1934 <tt>fcntl()</tt> and <tt>ioctl()</tt>.</li> 1935 </ul> 1936 1937 <p>You can detect support for these attributes with __has_attribute(). For 1938 example:</p> 1939 1940 <blockquote> 1941 <pre> 1942 #if defined(__has_attribute) 1943 # if __has_attribute(argument_with_type_tag) && \ 1944 __has_attribute(pointer_with_type_tag) && \ 1945 __has_attribute(type_tag_for_datatype) 1946 # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx))) 1947 /* ... other macros ... */ 1948 # endif 1949 #endif 1950 1951 #if !defined(ATTR_MPI_PWT) 1952 #define ATTR_MPI_PWT(buffer_idx, type_idx) 1953 #endif 1954 1955 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) 1956 ATTR_MPI_PWT(1,3); 1957 </pre> 1958 </blockquote> 1959 1960 <h3 id="argument_with_type_tag"><tt>argument_with_type_tag(...)</tt></h3> 1961 1962 <p>Use <tt>__attribute__((argument_with_type_tag(arg_kind, arg_idx, 1963 type_tag_idx)))</tt> on a function declaration to specify that the function 1964 accepts a type tag that determines the type of some other argument. 1965 <tt>arg_kind</tt> is an identifier that should be used when annotating all 1966 applicable type tags.</p> 1967 1968 <p>This attribute is primarily useful for checking arguments of variadic 1969 functions (<tt>pointer_with_type_tag</tt> can be used in most of non-variadic 1970 cases).</p> 1971 1972 <p>For example:</p> 1973 <blockquote> 1974 <pre> 1975 int fcntl(int fd, int cmd, ...) 1976 __attribute__(( argument_with_type_tag(fcntl,3,2) )); 1977 </pre> 1978 </blockquote> 1979 1980 <h3 id="pointer_with_type_tag"><tt>pointer_with_type_tag(...)</tt></h3> 1981 1982 <p>Use <tt>__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, 1983 type_tag_idx)))</tt> on a function declaration to specify that the 1984 function accepts a type tag that determines the pointee type of some other 1985 pointer argument.</p> 1986 1987 <p>For example:</p> 1988 <blockquote> 1989 <pre> 1990 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) 1991 __attribute__(( pointer_with_type_tag(mpi,1,3) )); 1992 </pre> 1993 </blockquote> 1994 1995 <h3 id="type_tag_for_datatype"><tt>type_tag_for_datatype(...)</tt></h3> 1996 1997 <p>Clang supports annotating type tags of two forms.</p> 1998 1999 <ul> 2000 <li><b>Type tag that is an expression containing a reference to some declared 2001 identifier.</b> Use <tt>__attribute__((type_tag_for_datatype(kind, type)))</tt> 2002 on a declaration with that identifier: 2003 2004 <blockquote> 2005 <pre> 2006 extern struct mpi_datatype mpi_datatype_int 2007 __attribute__(( type_tag_for_datatype(mpi,int) )); 2008 #define MPI_INT ((MPI_Datatype) &mpi_datatype_int) 2009 </pre> 2010 </blockquote></li> 2011 2012 <li><b>Type tag that is an integral literal.</b> Introduce a <tt>static 2013 const</tt> variable with a corresponding initializer value and attach 2014 <tt>__attribute__((type_tag_for_datatype(kind, type)))</tt> on that 2015 declaration, for example: 2016 2017 <blockquote> 2018 <pre> 2019 #define MPI_INT ((MPI_Datatype) 42) 2020 static const MPI_Datatype mpi_datatype_int 2021 __attribute__(( type_tag_for_datatype(mpi,int) )) = 42 2022 </pre> 2023 </blockquote></li> 2024 </ul> 2025 2026 <p>The attribute also accepts an optional third argument that determines how 2027 the expression is compared to the type tag. There are two supported flags:</p> 2028 2029 <ul><li><tt>layout_compatible</tt> will cause types to be compared according to 2030 layout-compatibility rules (C++11 [class.mem] p 17, 18). This is 2031 implemented to support annotating types like <tt>MPI_DOUBLE_INT</tt>. 2032 2033 <p>For example:</p> 2034 <blockquote> 2035 <pre> 2036 /* In mpi.h */ 2037 struct internal_mpi_double_int { double d; int i; }; 2038 extern struct mpi_datatype mpi_datatype_double_int 2039 __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, 2040 layout_compatible) )); 2041 2042 #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int) 2043 2044 /* In user code */ 2045 struct my_pair { double a; int b; }; 2046 struct my_pair *buffer; 2047 MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning 2048 2049 struct my_int_pair { int a; int b; } 2050 struct my_int_pair *buffer2; 2051 MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element 2052 // type 'struct my_int_pair' 2053 // doesn't match specified MPI_Datatype 2054 </pre> 2055 </blockquote> 2056 </li> 2057 2058 <li><tt>must_be_null</tt> specifies that the expression should be a null 2059 pointer constant, for example: 2060 2061 <blockquote> 2062 <pre> 2063 /* In mpi.h */ 2064 extern struct mpi_datatype mpi_datatype_null 2065 __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) )); 2066 2067 #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null) 2068 2069 /* In user code */ 2070 MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL 2071 // was specified but buffer 2072 // is not a null pointer 2073 </pre> 2074 </blockquote> 2075 </li> 2076 </ul> 2077 2078 </div> 2079 </body> 2080 </html> 2081
