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 159addition to the language extensions listed here, Clang aims to support a broad 160range of GCC extensions. Please see the <a 161href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for 162more 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 169on them. In order to allow fine-grain features checks, we support three builtin 170function-like macros. This allows you to directly test for a feature in your 171code without having to resort to something like autoconf or fragile "compiler 172version 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 179of a builtin function. It evaluates to 1 if the builtin is supported or 0 if 180not. 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 204name of a feature. <code>__has_feature</code> evaluates to 1 if the feature 205is both supported by Clang and standardized in the current language standard 206or 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 208Clang in the current language (either as a language extension or a standard 209language 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 236non-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"> 240Another use of <code>__has_feature</code> is to check for compiler features 241not 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 250following <code>__</code> (double underscore) to avoid interference from a macro 251with the same name. For instance, <code>__cxx_rvalue_references__</code> can be 252used 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 259of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It 260can 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 279following <code>__</code> (double underscore) to avoid interference from a macro 280with the same name. For instance, <code>__always_inline__</code> can be used 281instead 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. 288The <a href="#__has_include">__has_include</a> and 289<a href="#__has_include_next">__has_include_next</a> macros allow you to 290check for the existence of an include file before doing 291a 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 298is the name of an include file. It evaluates to 1 if the file can 299be 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 322is the name of an include file. It is like __has_include except that it 323looks for the second instance of the given file found in the include 324paths. It evaluates to 1 if the second instance of the file can 325be 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, 343and will issue a warning if used in the top-level compilation 344file. A warning will also be issued if an absolute path 345is 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 419support for <tt>V.xyzw</tt> syntax and other tidbits as seen in OpenCL. An 420example is:</p> 421 422<blockquote> 423<pre> 424typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>; 425typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>; 426 427float4 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 440syntax and functions. For example:</p> 441 442<blockquote> 443<pre> 444vector 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> 457typedef <b>__attribute__((neon_vector_type(8)))</b> int8_t int8x8_t; 458typedef <b>__attribute__((neon_polyvector_type(16)))</b> poly8_t poly8x16_t; 459 460int8x8_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 473vectors. Either parentheses or braces form can be used. In the parentheses form 474the number of literal values specified must be one, i.e. referring to a scalar 475value, or must match the size of the vector type being created. If a single 476scalar literal value is specified, the scalar literal value will be replicated 477to all the components of the vector type. In the brackets form any number of 478literals can be specified. For example:</p> 479 480<blockquote> 481<pre> 482typedef int v4si __attribute__((__vector_size__(16))); 483typedef float float4 __attribute__((ext_vector_type(4))); 484typedef float float2 __attribute__((ext_vector_type(2))); 485 486v4si vsi = (v4si){1, 2, 3, 4}; 487float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f); 488vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1). 489vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0). 490vector int vi3 = (vector int)(1, 2); // error 491vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0). 492vector int vi5 = (vector int)(1, 2, 3, 4); 493float4 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. 502A dash indicates that an operation is not accepted according to a corresponding 503specification.</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> 599and <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 606will 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 616with <tt>__has_extension(attribute_deprecated_with_message)</tt> 617and <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. 624This allows enumerators to be deprecated, made unavailable, etc. The 625attribute must appear after the enumerator name and before any 626initializer, 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 638individual 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 647that they will always be treated as being 'system frameworks', even if they are 648not present in a system framework directory. This can be useful to system 649framework developers who want to be able to test building other applications 650with development builds of their framework, including the manner in which the 651compiler 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 655framework 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 666should be treated as a system framework, regardless of how it was found in the 667framework search path. For consistency, we recommend that such files never be 668included 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 675be placed on declarations to describe the lifecycle of that 676declaration relative to operating system versions. Consider the function declaration for a hypothetical function <code>f</code>:</p> 677 678<pre> 679void 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 714version prior to when the declaration was introduced. When this 715happens, the declaration is <a 716 href="https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html">weakly 717linked</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 724language features are enabled. The <tt>__has_extension</tt> macro can be used 725to query if language features are available as an extension when compiling for 726a standard which does not provide them. The features which can be tested are 727listed 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 732enabled 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 737example, 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, 742compiling 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 747these features are enabled with the <tt>-std=c++11</tt> or <tt>-std=gnu++11</tt> 748option 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 758C++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 764specifiers 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 770parsing 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 775for generalized constant expressions (e.g., <tt>constexpr</tt>) is 776enabled.</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> 783does not require type-completeness of a function call expression. 784Use <tt>__has_feature(cxx_decltype_incomplete_return_types)</tt> 785or <tt>__has_extension(cxx_decltype_incomplete_return_types)</tt> 786to 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 792if 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 798defaulted 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 803support 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 809deleted 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 817support 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 823implicitly 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 833inline 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 839is 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 845support 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 851exception 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 867the 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 872if support for reference-qualified functions (e.g., member functions with 873<code>&</code> or <code>&&</code> applied to <code>*this</code>) 874is 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 880range-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 884for 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 890rvalue 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 896compile-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 902supported using the <tt>auto</tt> specifier. If this is disabled, <tt>auto</tt> 903will 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 909strongly 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 915alternate 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 919support 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 933for 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 938these features are enabled with the <tt>-std=c11</tt> or <tt>-std=gnu11</tt> 939option when compiling C code. Additionally, because these features are all 940backward-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> 945to determine if support for alignment specifiers using <tt>_Alignas</tt> 946is 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> 951to determine if support for atomic types using <tt>_Atomic</tt> is enabled. 952Clang also provides <a href="#__c11_atomic">a set of builtins</a> which can be 953used 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 960generic selections is enabled.</p> 961 962<p>As an extension, the C11 generic selection expression is available in all 963languages supported by Clang. The syntax is the same as that given in the 964C11 standard.</p> 965 966<p>In C, type compatibility is decided according to the rules given in the 967appropriate standard, but in C++, which lacks the type compatibility rules 968used 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 974compile-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) 984template<typename From, typename To> 985struct 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 1025href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI 1026details for the clang implementation are in <a 1027href="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> 1056NSArray *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 1062related 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 1065to 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 1068type <tt>instancetype</tt> as its result type. <tt>instancetype</tt> 1069is a contextual keyword that is only permitted in the result type of 1070an 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. 1079To determine whether a method has an inferred related result type, the first 1080word in the camel-case selector (e.g., "init" in "initWithObjects") is 1081considered, and the method will have a related result type if its return 1082type 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 1095method, the subclass method must also return a type that is compatible 1096with 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 1107property access via the given method. In all other respects, a method 1108with a related result type is treated the same way as method that 1109returns <tt>id</tt>.</p> 1110 1111<p>Use <tt>__has_feature(objc_instancetype)</tt> to determine whether 1112the <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 1125underlying type within Objective-C. For example, one can write an 1126enumeration type as:</p> 1127 1128<pre> 1129typedef enum : unsigned char { Red, Green, Blue } Color; 1130</pre> 1131 1132<p>This specifies that the underlying type, which is used to store the 1133enumeration value, is <tt>unsigned char</tt>.</p> 1134 1135<p>Use <tt>__has_feature(objc_fixed_enum)</tt> to determine whether 1136support 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 1143blocks-based APIs, by permitting a lambda to be implicitly converted 1144to a block pointer with the corresponding signature. For example, 1145consider an API such as <code>NSArray</code>'s array-sorting 1146method:</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 1152type are generally provided with block literals as arguments. However, 1153one can also use a C++11 lambda so long as it provides the same 1154signature (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 1174lambda expression (an unnamed, local class type called the <i>closure 1175type</i>) to the corresponding block pointer type. The conversion 1176itself is expressed by a conversion operator in that closure type 1177that produces a block pointer with the same signature as the lambda 1178itself, 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 1185the two parameters to the lambda object (which it captures by copy), 1186then returns the result. The returned block is first copied (with 1187<tt>Block_copy</tt>) and then autoreleased. As an optimization, if a 1188lambda expression is immediately converted to a block pointer (as in 1189the first example, above), then the block is not copied and 1190autoreleased: rather, it is given the same lifetime as a block literal 1191written at that point in the program, which avoids the overhead of 1192copying 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 1195in Objective-C++, and not in C++ with blocks, due to its use of 1196Objective-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 1203and Subscripting</a> in Objective-C, which simplifies common Objective-C 1204programming patterns, makes programs more concise, and improves the safety of 1205container creation. There are several feature macros associated with object 1206literals and subscripting: <code>__has_feature(objc_array_literals)</code> 1207tests the availability of array literals; 1208<code>__has_feature(objc_dictionary_literals)</code> tests the availability of 1209dictionary literals; <code>__has_feature(objc_subscripting)</code> tests the 1210availability 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 1217feature, clang provides default synthesis of those properties not declared @dynamic 1218and not having user provided backing getter and setter methods. 1219<code>__has_feature(objc_default_synthesize_properties)</code> checks for availability 1220of 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 1227overloading in C is introduced using the <tt>overloadable</tt> attribute. For 1228example, one might provide several overloaded versions of a <tt>tgsin</tt> 1229function that invokes the appropriate standard function computing the sine of a 1230value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt> 1231precision:</p> 1232 1233<blockquote> 1234<pre> 1235#include <math.h> 1236float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); } 1237double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); } 1238long 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 1245overloading in C follows the rules of C++ function overloading to pick 1246the best overload given the call arguments, with a few C-specific 1247semantics:</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 1263function declarations and definitions. Most importantly, if any 1264function with a given name is given the <tt>overloadable</tt> 1265attribute, then all function declarations and definitions with that 1266name (and in that scope) must have the <tt>overloadable</tt> 1267attribute. This rule even applies to redeclarations of functions whose original 1268declaration had the <tt>overloadable</tt> attribute, e.g.,</p> 1269 1270<blockquote> 1271<pre> 1272int f(int) __attribute__((overloadable)); 1273float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i> 1274 1275int g(int) __attribute__((overloadable)); 1276int 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 1281prototypes. Therefore, the following code is ill-formed:</p> 1282 1283<blockquote> 1284<pre> 1285int 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 1290ellipsis 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> 1294void 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 1299their names mangled according to the same rules as C++ function 1300names. For example, the three <tt>tgsin</tt> functions in our 1301motivating example get the mangled names <tt>_Z5tgsinf</tt>, 1302<tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two 1303caveats 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> 1332complex 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 1337initialize the real and imaginary parts of a complex variable in 1338standard C, given that clang does not support <code>_Imaginary</code>. 1339(clang also supports the <code>__real__</code> and <code>__imag__</code> 1340extensions from gcc, which help in some cases, but are not usable in 1341static initializers.) 1342 1343<p>Note that this extension does not allow eliding the braces; the 1344meaning of the following two lines is different:</p> 1345 1346<blockquote> 1347<pre> 1348complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1) 1349complex 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 1363GCC, 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 1366addition to the GCC builtins, Clang supports a number of builtins that GCC does 1367not, which are listed here.</p> 1368 1369<p>Please note that Clang does not and will not support all of the GCC builtins 1370for vector operations. Instead of using builtins, you should use the functions 1371defined in target-specific header files like <tt><xmmintrin.h></tt>, which 1372define portable wrappers for these. Many of the Clang versions of these 1373functions are implemented directly in terms of <a href="#vectors">extended 1374vector support</a> instead of builtins, in order to reduce the number of 1375builtins 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 1382register (or a similar low-latency, high-accuracy clock) on those targets that 1383support 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> 1395unsigned long long t0 = __builtin_readcyclecounter(); 1396do_something(); 1397unsigned long long t1 = __builtin_readcyclecounter(); 1398unsigned 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, 1404which may be either global or process/thread-specific depending on the target. 1405As the backing counters often overflow quickly (on the order of 1406seconds) this should only be used for timing small intervals. When not 1407supported by the target, the return value is always zero. This builtin 1408takes 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 1418permutation/shuffle/swizzle operations. This builtin is also very important for 1419the 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 1451same element type. The remaining arguments are a list of integers that specify 1452the elements indices of the first two vectors that should be extracted and 1453returned in a new vector. These element indices are numbered sequentially 1454starting with the first vector, continuing into the second vector. Thus, if 1455vec1 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 1459with the same element type as vec1/vec2 but that has an element count equal to 1460the 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 1470the program cannot be reached, even if the compiler might otherwise think it 1471can. This is useful to improve optimization and eliminates certain warnings. 1472For example, without the <tt>__builtin_unreachable</tt> in the example below, 1473the compiler assumes that the inline asm can fall through and prints a "function 1474declared '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> 1486void myabort(void) __attribute__((noreturn)); 1487void 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 1496it has undefined behavior, it is a statement that it is never reached and the 1497optimizer can take advantage of this to produce better code. This builtin takes 1498no 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 1508memory. 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> 1520int 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 1526intrinsics to allow code to atomically swap the current value with the new 1527value. More importantly, it helps developers write more efficient and correct 1528code by avoiding expensive loops around __sync_bool_compare_and_swap() or 1529relying 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 1538C11's <tt><stdatomic.h></tt> header. These builtins provide the semantics 1539of the <tt>_explicit</tt> form of the corresponding C11 operation, and are named 1540with 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 1572between switch labels. It can only be applied to a null statement placed at a 1573point of execution between any statement and the next switch label. It is common 1574to mark these places with a specific comment, but this attribute is meant to 1575replace comments with a more strict annotation, which can be checked by the 1576compiler. This attribute doesn't change semantics of the code and can be used 1577wherever an intended fall-through occurs. It is designed to mimic 1578control-flow statements like <tt>break;</tt>, so it can be placed in most places 1579where <tt>break;</tt> can, but only if there are no statements on the execution 1580path between it and the next switch label.</p> 1581<p>Here is an example:</p> 1582<pre> 1583// compile with -Wimplicit-fallthrough 1584switch (n) { 1585case 33: 1586 f(); 1587case 44: // warning: unannotated fall-through 1588 g(); 1589 <b>[[clang::fallthrough]];</b> 1590case 55: // no warning 1591 if (x) { 1592 h(); 1593 break; 1594 } 1595 else { 1596 i(); 1597 <b>[[clang::fallthrough]];</b> 1598 } 1599case 66: // no warning 1600 p(); 1601 <b>[[clang::fallthrough]];</b> // warning: fallthrough annotation does not directly precede case label 1602 q(); 1603case 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 1625relative to the X86 GS segment register, and address space #257 causes it to be 1626relative to the X86 FS segment. Note that this is a very very low-level 1627feature that should only be used if you know what you're doing (for example in 1628an OS kernel).</p> 1629 1630<p>Here is an example:</p> 1631 1632<pre> 1633#define GS_RELATIVE __attribute__((address_space(256))) 1634int 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 1653invariants and rules for static analysis tools. The extensions documented here 1654are used by the <a 1655href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer 1656engine</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> 1661attribute. This attribute, which is typically affixed to a function prototype, 1662indicates that a call to a given function never returns. Function prototypes for 1663common functions like <tt>exit</tt> are typically annotated with this attribute, 1664as well as a variety of common assertion handlers. Users can educate the static 1665analyzer about their own custom assertion handles (thus cutting down on false 1666positives due to false paths) by marking their own "panic" functions 1667with this attribute.</p> 1668 1669<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes 1670there are special functions that for all intents and purposes should be 1671considered panic functions (i.e., they are only called when an internal program 1672error occurs) but may actually return so that the program can fail gracefully. 1673The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions 1674as being interpreted as "no return" functions by the analyzer (thus 1675pruning 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 1679same places where the <tt>noreturn</tt> attribute can be placed. It is commonly 1680placed 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 1692by their selectors. For the purposes of static analysis, it is 1693sometimes useful to be able to mark a method as having a particular 1694conventional meaning despite not having the right selector, or as not 1695having the conventional meaning that its selector would suggest. 1696For these use cases, we provide an attribute to specifically describe 1697the <q>method family</q> that a method belongs to.</p> 1698 1699<p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>, 1700where <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 1702can 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 1709method, and who merely want to document its non-standard retain and 1710release semantics, should use the 1711<a href="#attr_retain_release">retaining behavior attributes</a> 1712described 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 1720and return objects with +0 retain counts, with some exceptions for 1721special methods like <tt>+alloc</tt> and <tt>init</tt>. However, 1722there are exceptions, and so Clang provides attributes to allow these 1723exceptions to be documented, which helps the analyzer find leaks (and 1724ignore non-leaks). Some exceptions may be better described using 1725the <a href="#attr_method_family"><tt>objc_method_family</tt></a> 1726attribute 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>, 1730and <tt>cf_returns_not_retained</tt> attributes can be placed on 1731methods and functions that return Objective-C or CoreFoundation 1732objects. They are commonly placed at the end of a function prototype 1733or 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 1742returned object has a +1 retain count. 1743The <tt>*_returns_not_retained</tt> attributes specify that the return 1744object has a +0 retain count, even if the normal convention for its 1745selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the 1746returned object is +0, but is guaranteed to live at least as long as the 1747next flush of an autorelease pool.</p> 1748 1749<p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt> 1750attributes can be placed on an parameter declaration; they specify 1751that the argument is expected to have a +1 retain count, which will be 1752balanced in some way by the function or method. 1753The <tt>ns_consumes_self</tt> attribute can only be placed on an 1754Objective-C method; it specifies that the method expects 1755its <tt>self</tt> parameter to have a +1 retain count, which it will 1756balance 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> 1773to 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 1777declaration to specify that address safety instrumentation (e.g. 1778AddressSanitizer) 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 1786multithreaded programs. 1787Clang currently parses the following list of attributes, although 1788<b>the implementation for these annotations is currently in development.</b> 1789For 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 1796declaration to specify that the thread safety analysis should not be run on that 1797function. This attribute provides an escape hatch (e.g. for situations when it 1798is 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 1803that it has a lockable type (e.g. a Mutex class). This annotation is primarily 1804used 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 1809specify that it has a "scoped" lockable type. Objects of this type will acquire 1810the lock upon construction and release it upon going out of scope. 1811 This annotation is primarily used to check 1812consistency.</p> 1813 1814<h4 id="ts_guardedvar">guarded_var</h4> 1815 1816<p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to 1817specify 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 1822specify 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 1827specify 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 1832specify 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 1837of a lockable variable to specify that the lock must be acquired before all 1838attribute arguments. Arguments must be lockable type, and there must be at 1839least one argument.</p> 1840 1841<h4 id="ts_acquiredafter">acquired_after(...)</h4> 1842 1843<p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration 1844of a lockable variable to specify that the lock must be acquired after all 1845attribute arguments. Arguments must be lockable type, and there must be at 1846least 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 1851declaration to specify that the function acquires all listed locks 1852exclusively. This attribute takes zero or more arguments: either of lockable 1853type or integers indexing into function parameters of lockable type. If no 1854arguments are given, the acquired lock is implicitly <tt>this</tt> of the 1855enclosing 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 1860declaration 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 1862arguments: either of lockable type or integers indexing into function 1863parameters of lockable type. If no arguments are given, the acquired lock is 1864implicitly <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 1869declaration to specify that the function will try (without blocking) to acquire 1870all listed locks exclusively. This attribute takes one or more arguments. The 1871first argument is an integer or boolean value specifying the return value of a 1872successful lock acquisition. The remaining arugments are either of lockable type 1873or integers indexing into function parameters of lockable type. If only one 1874argument is given, the acquired lock is implicitly <tt>this</tt> of the 1875enclosing 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 1880declaration to specify that the function will try (without blocking) to acquire 1881all listed locks, although the locks may be shared (e.g. read locks). This 1882attribute takes one or more arguments. The first argument is an integer or 1883boolean value specifying the return value of a successful lock acquisition. The 1884remaining arugments are either of lockable type or integers indexing into 1885function parameters of lockable type. If only one argument is given, the 1886acquired 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 1891declaration to specify that the function release all listed locks. This 1892attribute takes zero or more arguments: either of lockable type or integers 1893indexing into function parameters of lockable type. If no arguments are given, 1894the 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 1899declaration to specify that the function returns lock <tt>l</tt> (<tt>l</tt> 1900must be of lockable type). This annotation is used to aid in resolving lock 1901expressions.</p> 1902 1903<h4 id="ts_le">locks_excluded(...)</h4> 1904 1905<p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration 1906to specify that the function must not be called with the listed locks. Arguments 1907must 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 1912declaration to specify that the function must be called while holding the listed 1913exclusive locks. Arguments must be lockable type, and there must be at 1914least 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 1919declaration to specify that the function must be called while holding the listed 1920shared locks. Arguments must be lockable type, and there must be at 1921least 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 1928properties 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 1938example:</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 1955int 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, 1963type_tag_idx)))</tt> on a function declaration to specify that the function 1964accepts 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 1966applicable type tags.</p> 1967 1968<p>This attribute is primarily useful for checking arguments of variadic 1969functions (<tt>pointer_with_type_tag</tt> can be used in most of non-variadic 1970cases).</p> 1971 1972<p>For example:</p> 1973<blockquote> 1974<pre> 1975int 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, 1983type_tag_idx)))</tt> on a function declaration to specify that the 1984function accepts a type tag that determines the pointee type of some other 1985pointer argument.</p> 1986 1987<p>For example:</p> 1988<blockquote> 1989<pre> 1990int 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 2001identifier.</b> Use <tt>__attribute__((type_tag_for_datatype(kind, type)))</tt> 2002on a declaration with that identifier: 2003 2004<blockquote> 2005<pre> 2006extern 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 2013const</tt> variable with a corresponding initializer value and attach 2014<tt>__attribute__((type_tag_for_datatype(kind, type)))</tt> on that 2015declaration, for example: 2016 2017<blockquote> 2018<pre> 2019#define MPI_INT ((MPI_Datatype) 42) 2020static 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 2027the 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 2030layout-compatibility rules (C++11 [class.mem] p 17, 18). This is 2031implemented to support annotating types like <tt>MPI_DOUBLE_INT</tt>. 2032 2033<p>For example:</p> 2034<blockquote> 2035<pre> 2036/* In mpi.h */ 2037struct internal_mpi_double_int { double d; int i; }; 2038extern 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 */ 2045struct my_pair { double a; int b; }; 2046struct my_pair *buffer; 2047MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning 2048 2049struct my_int_pair { int a; int b; } 2050struct my_int_pair *buffer2; 2051MPI_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 2059pointer constant, for example: 2060 2061<blockquote> 2062<pre> 2063/* In mpi.h */ 2064extern 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 */ 2070MPI_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