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