1========================= 2Clang 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 MatrixTypes 17 18Introduction 19============ 20 21This document describes the language extensions provided by Clang. In addition 22to the language extensions listed here, Clang aims to support a broad range of 23GCC extensions. Please see the `GCC manual 24<https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on 25these extensions. 26 27.. _langext-feature_check: 28 29Feature Checking Macros 30======================= 31 32Language extensions can be very useful, but only if you know you can depend on 33them. In order to allow fine-grain features checks, we support three builtin 34function-like macros. This allows you to directly test for a feature in your 35code without having to resort to something like autoconf or fragile "compiler 36version checks". 37 38``__has_builtin`` 39----------------- 40 41This function-like macro takes a single identifier argument that is the name of 42a builtin function, a builtin pseudo-function (taking one or more type 43arguments), or a builtin template. 44It evaluates to 1 if the builtin is supported or 0 if not. 45It can be used like this: 46 47.. code-block:: c++ 48 49 #ifndef __has_builtin // Optional of course. 50 #define __has_builtin(x) 0 // Compatibility with non-clang compilers. 51 #endif 52 53 ... 54 #if __has_builtin(__builtin_trap) 55 __builtin_trap(); 56 #else 57 abort(); 58 #endif 59 ... 60 61.. note:: 62 63 Prior to Clang 10, ``__has_builtin`` could not be used to detect most builtin 64 pseudo-functions. 65 66 ``__has_builtin`` should not be used to detect support for a builtin macro; 67 use ``#ifdef`` instead. 68 69.. _langext-__has_feature-__has_extension: 70 71``__has_feature`` and ``__has_extension`` 72----------------------------------------- 73 74These function-like macros take a single identifier argument that is the name 75of a feature. ``__has_feature`` evaluates to 1 if the feature is both 76supported by Clang and standardized in the current language standard or 0 if 77not (but see :ref:`below <langext-has-feature-back-compat>`), while 78``__has_extension`` evaluates to 1 if the feature is supported by Clang in the 79current language (either as a language extension or a standard language 80feature) or 0 if not. They can be used like this: 81 82.. code-block:: c++ 83 84 #ifndef __has_feature // Optional of course. 85 #define __has_feature(x) 0 // Compatibility with non-clang compilers. 86 #endif 87 #ifndef __has_extension 88 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers. 89 #endif 90 91 ... 92 #if __has_feature(cxx_rvalue_references) 93 // This code will only be compiled with the -std=c++11 and -std=gnu++11 94 // options, because rvalue references are only standardized in C++11. 95 #endif 96 97 #if __has_extension(cxx_rvalue_references) 98 // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98 99 // and -std=gnu++98 options, because rvalue references are supported as a 100 // language extension in C++98. 101 #endif 102 103.. _langext-has-feature-back-compat: 104 105For backward compatibility, ``__has_feature`` can also be used to test 106for support for non-standardized features, i.e. features not prefixed ``c_``, 107``cxx_`` or ``objc_``. 108 109Another use of ``__has_feature`` is to check for compiler features not related 110to the language standard, such as e.g. :doc:`AddressSanitizer 111<AddressSanitizer>`. 112 113If the ``-pedantic-errors`` option is given, ``__has_extension`` is equivalent 114to ``__has_feature``. 115 116The feature tag is described along with the language feature below. 117 118The feature name or extension name can also be specified with a preceding and 119following ``__`` (double underscore) to avoid interference from a macro with 120the same name. For instance, ``__cxx_rvalue_references__`` can be used instead 121of ``cxx_rvalue_references``. 122 123``__has_cpp_attribute`` 124----------------------- 125 126This function-like macro is available in C++20 by default, and is provided as an 127extension in earlier language standards. It takes a single argument that is the 128name of a double-square-bracket-style attribute. The argument can either be a 129single identifier or a scoped identifier. If the attribute is supported, a 130nonzero value is returned. If the attribute is a standards-based attribute, this 131macro returns a nonzero value based on the year and month in which the attribute 132was voted into the working draft. See `WG21 SD-6 133<https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations>`_ 134for the list of values returned for standards-based attributes. If the attribute 135is not supported by the current compilation target, this macro evaluates to 0. 136It can be used like this: 137 138.. code-block:: c++ 139 140 #ifndef __has_cpp_attribute // For backwards compatibility 141 #define __has_cpp_attribute(x) 0 142 #endif 143 144 ... 145 #if __has_cpp_attribute(clang::fallthrough) 146 #define FALLTHROUGH [[clang::fallthrough]] 147 #else 148 #define FALLTHROUGH 149 #endif 150 ... 151 152The attribute scope tokens ``clang`` and ``_Clang`` are interchangeable, as are 153the attribute scope tokens ``gnu`` and ``__gnu__``. Attribute tokens in either 154of these namespaces can be specified with a preceding and following ``__`` 155(double underscore) to avoid interference from a macro with the same name. For 156instance, ``gnu::__const__`` can be used instead of ``gnu::const``. 157 158``__has_c_attribute`` 159--------------------- 160 161This function-like macro takes a single argument that is the name of an 162attribute exposed with the double square-bracket syntax in C mode. The argument 163can either be a single identifier or a scoped identifier. If the attribute is 164supported, a nonzero value is returned. If the attribute is not supported by the 165current compilation target, this macro evaluates to 0. It can be used like this: 166 167.. code-block:: c 168 169 #ifndef __has_c_attribute // Optional of course. 170 #define __has_c_attribute(x) 0 // Compatibility with non-clang compilers. 171 #endif 172 173 ... 174 #if __has_c_attribute(fallthrough) 175 #define FALLTHROUGH [[fallthrough]] 176 #else 177 #define FALLTHROUGH 178 #endif 179 ... 180 181The attribute scope tokens ``clang`` and ``_Clang`` are interchangeable, as are 182the attribute scope tokens ``gnu`` and ``__gnu__``. Attribute tokens in either 183of these namespaces can be specified with a preceding and following ``__`` 184(double underscore) to avoid interference from a macro with the same name. For 185instance, ``gnu::__const__`` can be used instead of ``gnu::const``. 186 187``__has_attribute`` 188------------------- 189 190This function-like macro takes a single identifier argument that is the name of 191a GNU-style attribute. It evaluates to 1 if the attribute is supported by the 192current compilation target, or 0 if not. It can be used like this: 193 194.. code-block:: c++ 195 196 #ifndef __has_attribute // Optional of course. 197 #define __has_attribute(x) 0 // Compatibility with non-clang compilers. 198 #endif 199 200 ... 201 #if __has_attribute(always_inline) 202 #define ALWAYS_INLINE __attribute__((always_inline)) 203 #else 204 #define ALWAYS_INLINE 205 #endif 206 ... 207 208The attribute name can also be specified with a preceding and following ``__`` 209(double underscore) to avoid interference from a macro with the same name. For 210instance, ``__always_inline__`` can be used instead of ``always_inline``. 211 212 213``__has_declspec_attribute`` 214---------------------------- 215 216This function-like macro takes a single identifier argument that is the name of 217an attribute implemented as a Microsoft-style ``__declspec`` attribute. It 218evaluates to 1 if the attribute is supported by the current compilation target, 219or 0 if not. It can be used like this: 220 221.. code-block:: c++ 222 223 #ifndef __has_declspec_attribute // Optional of course. 224 #define __has_declspec_attribute(x) 0 // Compatibility with non-clang compilers. 225 #endif 226 227 ... 228 #if __has_declspec_attribute(dllexport) 229 #define DLLEXPORT __declspec(dllexport) 230 #else 231 #define DLLEXPORT 232 #endif 233 ... 234 235The attribute name can also be specified with a preceding and following ``__`` 236(double underscore) to avoid interference from a macro with the same name. For 237instance, ``__dllexport__`` can be used instead of ``dllexport``. 238 239``__is_identifier`` 240------------------- 241 242This function-like macro takes a single identifier argument that might be either 243a reserved word or a regular identifier. It evaluates to 1 if the argument is just 244a regular identifier and not a reserved word, in the sense that it can then be 245used as the name of a user-defined function or variable. Otherwise it evaluates 246to 0. It can be used like this: 247 248.. code-block:: c++ 249 250 ... 251 #ifdef __is_identifier // Compatibility with non-clang compilers. 252 #if __is_identifier(__wchar_t) 253 typedef wchar_t __wchar_t; 254 #endif 255 #endif 256 257 __wchar_t WideCharacter; 258 ... 259 260Include File Checking Macros 261============================ 262 263Not all developments systems have the same include files. The 264:ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow 265you to check for the existence of an include file before doing a possibly 266failing ``#include`` directive. Include file checking macros must be used 267as expressions in ``#if`` or ``#elif`` preprocessing directives. 268 269.. _langext-__has_include: 270 271``__has_include`` 272----------------- 273 274This function-like macro takes a single file name string argument that is the 275name of an include file. It evaluates to 1 if the file can be found using the 276include paths, or 0 otherwise: 277 278.. code-block:: c++ 279 280 // Note the two possible file name string formats. 281 #if __has_include("myinclude.h") && __has_include(<stdint.h>) 282 # include "myinclude.h" 283 #endif 284 285To test for this feature, use ``#if defined(__has_include)``: 286 287.. code-block:: c++ 288 289 // To avoid problem with non-clang compilers not having this macro. 290 #if defined(__has_include) 291 #if __has_include("myinclude.h") 292 # include "myinclude.h" 293 #endif 294 #endif 295 296.. _langext-__has_include_next: 297 298``__has_include_next`` 299---------------------- 300 301This function-like macro takes a single file name string argument that is the 302name of an include file. It is like ``__has_include`` except that it looks for 303the second instance of the given file found in the include paths. It evaluates 304to 1 if the second instance of the file can be found using the include paths, 305or 0 otherwise: 306 307.. code-block:: c++ 308 309 // Note the two possible file name string formats. 310 #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>) 311 # include_next "myinclude.h" 312 #endif 313 314 // To avoid problem with non-clang compilers not having this macro. 315 #if defined(__has_include_next) 316 #if __has_include_next("myinclude.h") 317 # include_next "myinclude.h" 318 #endif 319 #endif 320 321Note that ``__has_include_next``, like the GNU extension ``#include_next`` 322directive, is intended for use in headers only, and will issue a warning if 323used in the top-level compilation file. A warning will also be issued if an 324absolute path is used in the file argument. 325 326``__has_warning`` 327----------------- 328 329This function-like macro takes a string literal that represents a command line 330option for a warning and returns true if that is a valid warning option. 331 332.. code-block:: c++ 333 334 #if __has_warning("-Wformat") 335 ... 336 #endif 337 338.. _languageextensions-builtin-macros: 339 340Builtin Macros 341============== 342 343``__BASE_FILE__`` 344 Defined to a string that contains the name of the main input file passed to 345 Clang. 346 347``__FILE_NAME__`` 348 Clang-specific extension that functions similar to ``__FILE__`` but only 349 renders the last path component (the filename) instead of an invocation 350 dependent full path to that file. 351 352``__COUNTER__`` 353 Defined to an integer value that starts at zero and is incremented each time 354 the ``__COUNTER__`` macro is expanded. 355 356``__INCLUDE_LEVEL__`` 357 Defined to an integral value that is the include depth of the file currently 358 being translated. For the main file, this value is zero. 359 360``__TIMESTAMP__`` 361 Defined to the date and time of the last modification of the current source 362 file. 363 364``__clang__`` 365 Defined when compiling with Clang 366 367``__clang_major__`` 368 Defined to the major marketing version number of Clang (e.g., the 2 in 369 2.0.1). Note that marketing version numbers should not be used to check for 370 language features, as different vendors use different numbering schemes. 371 Instead, use the :ref:`langext-feature_check`. 372 373``__clang_minor__`` 374 Defined to the minor version number of Clang (e.g., the 0 in 2.0.1). Note 375 that marketing version numbers should not be used to check for language 376 features, as different vendors use different numbering schemes. Instead, use 377 the :ref:`langext-feature_check`. 378 379``__clang_patchlevel__`` 380 Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1). 381 382``__clang_version__`` 383 Defined to a string that captures the Clang marketing version, including the 384 Subversion tag or revision number, e.g., "``1.5 (trunk 102332)``". 385 386``__clang_literal_encoding__`` 387 Defined to a narrow string literal that represents the current encoding of 388 narrow string literals, e.g., ``"hello"``. This macro typically expands to 389 "UTF-8" (but may change in the future if the 390 ``-fexec-charset="Encoding-Name"`` option is implemented.) 391 392``__clang_wide_literal_encoding__`` 393 Defined to a narrow string literal that represents the current encoding of 394 wide string literals, e.g., ``L"hello"``. This macro typically expands to 395 "UTF-16" or "UTF-32" (but may change in the future if the 396 ``-fwide-exec-charset="Encoding-Name"`` option is implemented.) 397 398.. _langext-vectors: 399 400Vectors and Extended Vectors 401============================ 402 403Supports the GCC, OpenCL, AltiVec and NEON vector extensions. 404 405OpenCL vector types are created using the ``ext_vector_type`` attribute. It 406supports the ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example 407is: 408 409.. code-block:: c++ 410 411 typedef float float4 __attribute__((ext_vector_type(4))); 412 typedef float float2 __attribute__((ext_vector_type(2))); 413 414 float4 foo(float2 a, float2 b) { 415 float4 c; 416 c.xz = a; 417 c.yw = b; 418 return c; 419 } 420 421Query for this feature with ``__has_attribute(ext_vector_type)``. 422 423Giving ``-maltivec`` option to clang enables support for AltiVec vector syntax 424and functions. For example: 425 426.. code-block:: c++ 427 428 vector float foo(vector int a) { 429 vector int b; 430 b = vec_add(a, a) + a; 431 return (vector float)b; 432 } 433 434NEON vector types are created using ``neon_vector_type`` and 435``neon_polyvector_type`` attributes. For example: 436 437.. code-block:: c++ 438 439 typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t; 440 typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t; 441 442 int8x8_t foo(int8x8_t a) { 443 int8x8_t v; 444 v = a; 445 return v; 446 } 447 448Vector Literals 449--------------- 450 451Vector literals can be used to create vectors from a set of scalars, or 452vectors. Either parentheses or braces form can be used. In the parentheses 453form the number of literal values specified must be one, i.e. referring to a 454scalar value, or must match the size of the vector type being created. If a 455single scalar literal value is specified, the scalar literal value will be 456replicated to all the components of the vector type. In the brackets form any 457number of literals can be specified. For example: 458 459.. code-block:: c++ 460 461 typedef int v4si __attribute__((__vector_size__(16))); 462 typedef float float4 __attribute__((ext_vector_type(4))); 463 typedef float float2 __attribute__((ext_vector_type(2))); 464 465 v4si vsi = (v4si){1, 2, 3, 4}; 466 float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f); 467 vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1). 468 vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0). 469 vector int vi3 = (vector int)(1, 2); // error 470 vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0). 471 vector int vi5 = (vector int)(1, 2, 3, 4); 472 float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f)); 473 474Vector Operations 475----------------- 476 477The table below shows the support for each operation by vector extension. A 478dash indicates that an operation is not accepted according to a corresponding 479specification. 480 481============================== ======= ======= ============= ======= 482 Operator OpenCL AltiVec GCC NEON 483============================== ======= ======= ============= ======= 484[] yes yes yes -- 485unary operators +, -- yes yes yes -- 486++, -- -- yes yes yes -- 487+,--,*,/,% yes yes yes -- 488bitwise operators &,|,^,~ yes yes yes -- 489>>,<< yes yes yes -- 490!, &&, || yes -- yes -- 491==, !=, >, <, >=, <= yes yes yes -- 492= yes yes yes yes 493?: [#]_ yes -- yes -- 494sizeof yes yes yes yes 495C-style cast yes yes yes no 496reinterpret_cast yes no yes no 497static_cast yes no yes no 498const_cast no no no no 499============================== ======= ======= ============= ======= 500 501See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`. 502 503.. [#] ternary operator(?:) has different behaviors depending on condition 504 operand's vector type. If the condition is a GNU vector (i.e. __vector_size__), 505 it's only available in C++ and uses normal bool conversions (that is, != 0). 506 If it's an extension (OpenCL) vector, it's only available in C and OpenCL C. 507 And it selects base on signedness of the condition operands (OpenCL v1.1 s6.3.9). 508 509Matrix Types 510============ 511 512Clang provides an extension for matrix types, which is currently being 513implemented. See :ref:`the draft specification <matrixtypes>` for more details. 514 515For example, the code below uses the matrix types extension to multiply two 4x4 516float matrices and add the result to a third 4x4 matrix. 517 518.. code-block:: c++ 519 520 typedef float m4x4_t __attribute__((matrix_type(4, 4))); 521 522 m4x4_t f(m4x4_t a, m4x4_t b, m4x4_t c) { 523 return a + b * c; 524 } 525 526The matrix type extension also supports operations on a matrix and a scalar. 527 528.. code-block:: c++ 529 530 typedef float m4x4_t __attribute__((matrix_type(4, 4))); 531 532 m4x4_t f(m4x4_t a) { 533 return (a + 23) * 12; 534 } 535 536The matrix type extension supports division on a matrix and a scalar but not on a matrix and a matrix. 537 538.. code-block:: c++ 539 540 typedef float m4x4_t __attribute__((matrix_type(4, 4))); 541 542 m4x4_t f(m4x4_t a) { 543 a = a / 3.0; 544 return a; 545 } 546 547The matrix type extension supports compound assignments for addition, subtraction, and multiplication on matrices 548and on a matrix and a scalar, provided their types are consistent. 549 550.. code-block:: c++ 551 552 typedef float m4x4_t __attribute__((matrix_type(4, 4))); 553 554 m4x4_t f(m4x4_t a, m4x4_t b) { 555 a += b; 556 a -= b; 557 a *= b; 558 a += 23; 559 a -= 12; 560 return a; 561 } 562 563The matrix type extension supports explicit casts. Implicit type conversion between matrix types is not allowed. 564 565.. code-block:: c++ 566 567 typedef int ix5x5 __attribute__((matrix_type(5, 5))); 568 typedef float fx5x5 __attribute__((matrix_type(5, 5))); 569 570 fx5x5 f1(ix5x5 i, fx5x5 f) { 571 return (fx5x5) i; 572 } 573 574 575 template <typename X> 576 using matrix_4_4 = X __attribute__((matrix_type(4, 4))); 577 578 void f2() { 579 matrix_5_5<double> d; 580 matrix_5_5<int> i; 581 i = (matrix_5_5<int>)d; 582 i = static_cast<matrix_5_5<int>>(d); 583 } 584 585Half-Precision Floating Point 586============================= 587 588Clang supports three half-precision (16-bit) floating point types: ``__fp16``, 589``_Float16`` and ``__bf16``. These types are supported in all language modes. 590 591``__fp16`` is supported on every target, as it is purely a storage format; see below. 592``_Float16`` is currently only supported on the following targets, with further 593targets pending ABI standardization: 594 595* 32-bit ARM 596* 64-bit ARM (AArch64) 597* AMDGPU 598* SPIR 599* X86 (Only available under feature AVX512-FP16) 600 601``_Float16`` will be supported on more targets as they define ABIs for it. 602 603``__bf16`` is purely a storage format; it is currently only supported on the following targets: 604* 32-bit ARM 605* 64-bit ARM (AArch64) 606 607The ``__bf16`` type is only available when supported in hardware. 608 609``__fp16`` is a storage and interchange format only. This means that values of 610``__fp16`` are immediately promoted to (at least) ``float`` when used in arithmetic 611operations, so that e.g. the result of adding two ``__fp16`` values has type ``float``. 612The behavior of ``__fp16`` is specified by the ARM C Language Extensions (`ACLE <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053d/IHI0053D_acle_2_1.pdf>`_). 613Clang uses the ``binary16`` format from IEEE 754-2008 for ``__fp16``, not the ARM 614alternative format. 615 616``_Float16`` is an interchange floating-point type. This means that, just like arithmetic on 617``float`` or ``double``, arithmetic on ``_Float16`` operands is formally performed in the 618``_Float16`` type, so that e.g. the result of adding two ``_Float16`` values has type 619``_Float16``. The behavior of ``_Float16`` is specified by ISO/IEC TS 18661-3:2015 620("Floating-point extensions for C"). As with ``__fp16``, Clang uses the ``binary16`` 621format from IEEE 754-2008 for ``_Float16``. 622 623``_Float16`` arithmetic will be performed using native half-precision support 624when available on the target (e.g. on ARMv8.2a); otherwise it will be performed 625at a higher precision (currently always ``float``) and then truncated down to 626``_Float16``. Note that C and C++ allow intermediate floating-point operands 627of an expression to be computed with greater precision than is expressible in 628their type, so Clang may avoid intermediate truncations in certain cases; this may 629lead to results that are inconsistent with native arithmetic. 630 631It is recommended that portable code use ``_Float16`` instead of ``__fp16``, 632as it has been defined by the C standards committee and has behavior that is 633more familiar to most programmers. 634 635Because ``__fp16`` operands are always immediately promoted to ``float``, the 636common real type of ``__fp16`` and ``_Float16`` for the purposes of the usual 637arithmetic conversions is ``float``. 638 639A literal can be given ``_Float16`` type using the suffix ``f16``. For example, 640``3.14f16``. 641 642Because default argument promotion only applies to the standard floating-point 643types, ``_Float16`` values are not promoted to ``double`` when passed as variadic 644or untyped arguments. As a consequence, some caution must be taken when using 645certain library facilities with ``_Float16``; for example, there is no ``printf`` format 646specifier for ``_Float16``, and (unlike ``float``) it will not be implicitly promoted to 647``double`` when passed to ``printf``, so the programmer must explicitly cast it to 648``double`` before using it with an ``%f`` or similar specifier. 649 650Messages on ``deprecated`` and ``unavailable`` Attributes 651========================================================= 652 653An optional string message can be added to the ``deprecated`` and 654``unavailable`` attributes. For example: 655 656.. code-block:: c++ 657 658 void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!"))); 659 660If the deprecated or unavailable declaration is used, the message will be 661incorporated into the appropriate diagnostic: 662 663.. code-block:: none 664 665 harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! 666 [-Wdeprecated-declarations] 667 explode(); 668 ^ 669 670Query for this feature with 671``__has_extension(attribute_deprecated_with_message)`` and 672``__has_extension(attribute_unavailable_with_message)``. 673 674Attributes on Enumerators 675========================= 676 677Clang allows attributes to be written on individual enumerators. This allows 678enumerators to be deprecated, made unavailable, etc. The attribute must appear 679after the enumerator name and before any initializer, like so: 680 681.. code-block:: c++ 682 683 enum OperationMode { 684 OM_Invalid, 685 OM_Normal, 686 OM_Terrified __attribute__((deprecated)), 687 OM_AbortOnError __attribute__((deprecated)) = 4 688 }; 689 690Attributes on the ``enum`` declaration do not apply to individual enumerators. 691 692Query for this feature with ``__has_extension(enumerator_attributes)``. 693 694C++11 Attributes on using-declarations 695====================================== 696 697Clang allows C++-style ``[[]]`` attributes to be written on using-declarations. 698For instance: 699 700.. code-block:: c++ 701 702 [[clang::using_if_exists]] using foo::bar; 703 using foo::baz [[clang::using_if_exists]]; 704 705You can test for support for this extension with 706``__has_extension(cxx_attributes_on_using_declarations)``. 707 708'User-Specified' System Frameworks 709================================== 710 711Clang provides a mechanism by which frameworks can be built in such a way that 712they will always be treated as being "system frameworks", even if they are not 713present in a system framework directory. This can be useful to system 714framework developers who want to be able to test building other applications 715with development builds of their framework, including the manner in which the 716compiler changes warning behavior for system headers. 717 718Framework developers can opt-in to this mechanism by creating a 719"``.system_framework``" file at the top-level of their framework. That is, the 720framework should have contents like: 721 722.. code-block:: none 723 724 .../TestFramework.framework 725 .../TestFramework.framework/.system_framework 726 .../TestFramework.framework/Headers 727 .../TestFramework.framework/Headers/TestFramework.h 728 ... 729 730Clang will treat the presence of this file as an indicator that the framework 731should be treated as a system framework, regardless of how it was found in the 732framework search path. For consistency, we recommend that such files never be 733included in installed versions of the framework. 734 735Checks for Standard Language Features 736===================================== 737 738The ``__has_feature`` macro can be used to query if certain standard language 739features are enabled. The ``__has_extension`` macro can be used to query if 740language features are available as an extension when compiling for a standard 741which does not provide them. The features which can be tested are listed here. 742 743Since Clang 3.4, the C++ SD-6 feature test macros are also supported. 744These are macros with names of the form ``__cpp_<feature_name>``, and are 745intended to be a portable way to query the supported features of the compiler. 746See `the C++ status page <https://clang.llvm.org/cxx_status.html#ts>`_ for 747information on the version of SD-6 supported by each Clang release, and the 748macros provided by that revision of the recommendations. 749 750C++98 751----- 752 753The features listed below are part of the C++98 standard. These features are 754enabled by default when compiling C++ code. 755 756C++ exceptions 757^^^^^^^^^^^^^^ 758 759Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been 760enabled. For example, compiling code with ``-fno-exceptions`` disables C++ 761exceptions. 762 763C++ RTTI 764^^^^^^^^ 765 766Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For 767example, compiling code with ``-fno-rtti`` disables the use of RTTI. 768 769C++11 770----- 771 772The features listed below are part of the C++11 standard. As a result, all 773these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option 774when compiling C++ code. 775 776C++11 SFINAE includes access control 777^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 778 779Use ``__has_feature(cxx_access_control_sfinae)`` or 780``__has_extension(cxx_access_control_sfinae)`` to determine whether 781access-control errors (e.g., calling a private constructor) are considered to 782be template argument deduction errors (aka SFINAE errors), per `C++ DR1170 783<http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170>`_. 784 785C++11 alias templates 786^^^^^^^^^^^^^^^^^^^^^ 787 788Use ``__has_feature(cxx_alias_templates)`` or 789``__has_extension(cxx_alias_templates)`` to determine if support for C++11's 790alias declarations and alias templates is enabled. 791 792C++11 alignment specifiers 793^^^^^^^^^^^^^^^^^^^^^^^^^^ 794 795Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to 796determine if support for alignment specifiers using ``alignas`` is enabled. 797 798Use ``__has_feature(cxx_alignof)`` or ``__has_extension(cxx_alignof)`` to 799determine if support for the ``alignof`` keyword is enabled. 800 801C++11 attributes 802^^^^^^^^^^^^^^^^ 803 804Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to 805determine if support for attribute parsing with C++11's square bracket notation 806is enabled. 807 808C++11 generalized constant expressions 809^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 810 811Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized 812constant expressions (e.g., ``constexpr``) is enabled. 813 814C++11 ``decltype()`` 815^^^^^^^^^^^^^^^^^^^^ 816 817Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to 818determine if support for the ``decltype()`` specifier is enabled. C++11's 819``decltype`` does not require type-completeness of a function call expression. 820Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or 821``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if 822support for this feature is enabled. 823 824C++11 default template arguments in function templates 825^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 826 827Use ``__has_feature(cxx_default_function_template_args)`` or 828``__has_extension(cxx_default_function_template_args)`` to determine if support 829for default template arguments in function templates is enabled. 830 831C++11 ``default``\ ed functions 832^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 833 834Use ``__has_feature(cxx_defaulted_functions)`` or 835``__has_extension(cxx_defaulted_functions)`` to determine if support for 836defaulted function definitions (with ``= default``) is enabled. 837 838C++11 delegating constructors 839^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 840 841Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for 842delegating constructors is enabled. 843 844C++11 ``deleted`` functions 845^^^^^^^^^^^^^^^^^^^^^^^^^^^ 846 847Use ``__has_feature(cxx_deleted_functions)`` or 848``__has_extension(cxx_deleted_functions)`` to determine if support for deleted 849function definitions (with ``= delete``) is enabled. 850 851C++11 explicit conversion functions 852^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 853 854Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for 855``explicit`` conversion functions is enabled. 856 857C++11 generalized initializers 858^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 859 860Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for 861generalized initializers (using braced lists and ``std::initializer_list``) is 862enabled. 863 864C++11 implicit move constructors/assignment operators 865^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 866 867Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly 868generate move constructors and move assignment operators where needed. 869 870C++11 inheriting constructors 871^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 872 873Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for 874inheriting constructors is enabled. 875 876C++11 inline namespaces 877^^^^^^^^^^^^^^^^^^^^^^^ 878 879Use ``__has_feature(cxx_inline_namespaces)`` or 880``__has_extension(cxx_inline_namespaces)`` to determine if support for inline 881namespaces is enabled. 882 883C++11 lambdas 884^^^^^^^^^^^^^ 885 886Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to 887determine if support for lambdas is enabled. 888 889C++11 local and unnamed types as template arguments 890^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 891 892Use ``__has_feature(cxx_local_type_template_args)`` or 893``__has_extension(cxx_local_type_template_args)`` to determine if support for 894local and unnamed types as template arguments is enabled. 895 896C++11 noexcept 897^^^^^^^^^^^^^^ 898 899Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to 900determine if support for noexcept exception specifications is enabled. 901 902C++11 in-class non-static data member initialization 903^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 904 905Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class 906initialization of non-static data members is enabled. 907 908C++11 ``nullptr`` 909^^^^^^^^^^^^^^^^^ 910 911Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to 912determine if support for ``nullptr`` is enabled. 913 914C++11 ``override control`` 915^^^^^^^^^^^^^^^^^^^^^^^^^^ 916 917Use ``__has_feature(cxx_override_control)`` or 918``__has_extension(cxx_override_control)`` to determine if support for the 919override control keywords is enabled. 920 921C++11 reference-qualified functions 922^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 923 924Use ``__has_feature(cxx_reference_qualified_functions)`` or 925``__has_extension(cxx_reference_qualified_functions)`` to determine if support 926for reference-qualified functions (e.g., member functions with ``&`` or ``&&`` 927applied to ``*this``) is enabled. 928 929C++11 range-based ``for`` loop 930^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 931 932Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to 933determine if support for the range-based for loop is enabled. 934 935C++11 raw string literals 936^^^^^^^^^^^^^^^^^^^^^^^^^ 937 938Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw 939string literals (e.g., ``R"x(foo\bar)x"``) is enabled. 940 941C++11 rvalue references 942^^^^^^^^^^^^^^^^^^^^^^^ 943 944Use ``__has_feature(cxx_rvalue_references)`` or 945``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue 946references is enabled. 947 948C++11 ``static_assert()`` 949^^^^^^^^^^^^^^^^^^^^^^^^^ 950 951Use ``__has_feature(cxx_static_assert)`` or 952``__has_extension(cxx_static_assert)`` to determine if support for compile-time 953assertions using ``static_assert`` is enabled. 954 955C++11 ``thread_local`` 956^^^^^^^^^^^^^^^^^^^^^^ 957 958Use ``__has_feature(cxx_thread_local)`` to determine if support for 959``thread_local`` variables is enabled. 960 961C++11 type inference 962^^^^^^^^^^^^^^^^^^^^ 963 964Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to 965determine C++11 type inference is supported using the ``auto`` specifier. If 966this is disabled, ``auto`` will instead be a storage class specifier, as in C 967or C++98. 968 969C++11 strongly typed enumerations 970^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 971 972Use ``__has_feature(cxx_strong_enums)`` or 973``__has_extension(cxx_strong_enums)`` to determine if support for strongly 974typed, scoped enumerations is enabled. 975 976C++11 trailing return type 977^^^^^^^^^^^^^^^^^^^^^^^^^^ 978 979Use ``__has_feature(cxx_trailing_return)`` or 980``__has_extension(cxx_trailing_return)`` to determine if support for the 981alternate function declaration syntax with trailing return type is enabled. 982 983C++11 Unicode string literals 984^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 985 986Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode 987string literals is enabled. 988 989C++11 unrestricted unions 990^^^^^^^^^^^^^^^^^^^^^^^^^ 991 992Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for 993unrestricted unions is enabled. 994 995C++11 user-defined literals 996^^^^^^^^^^^^^^^^^^^^^^^^^^^ 997 998Use ``__has_feature(cxx_user_literals)`` to determine if support for 999user-defined literals is enabled. 1000 1001C++11 variadic templates 1002^^^^^^^^^^^^^^^^^^^^^^^^ 1003 1004Use ``__has_feature(cxx_variadic_templates)`` or 1005``__has_extension(cxx_variadic_templates)`` to determine if support for 1006variadic templates is enabled. 1007 1008C++14 1009----- 1010 1011The features listed below are part of the C++14 standard. As a result, all 1012these features are enabled with the ``-std=C++14`` or ``-std=gnu++14`` option 1013when compiling C++ code. 1014 1015C++14 binary literals 1016^^^^^^^^^^^^^^^^^^^^^ 1017 1018Use ``__has_feature(cxx_binary_literals)`` or 1019``__has_extension(cxx_binary_literals)`` to determine whether 1020binary literals (for instance, ``0b10010``) are recognized. Clang supports this 1021feature as an extension in all language modes. 1022 1023C++14 contextual conversions 1024^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1025 1026Use ``__has_feature(cxx_contextual_conversions)`` or 1027``__has_extension(cxx_contextual_conversions)`` to determine if the C++14 rules 1028are used when performing an implicit conversion for an array bound in a 1029*new-expression*, the operand of a *delete-expression*, an integral constant 1030expression, or a condition in a ``switch`` statement. 1031 1032C++14 decltype(auto) 1033^^^^^^^^^^^^^^^^^^^^ 1034 1035Use ``__has_feature(cxx_decltype_auto)`` or 1036``__has_extension(cxx_decltype_auto)`` to determine if support 1037for the ``decltype(auto)`` placeholder type is enabled. 1038 1039C++14 default initializers for aggregates 1040^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1041 1042Use ``__has_feature(cxx_aggregate_nsdmi)`` or 1043``__has_extension(cxx_aggregate_nsdmi)`` to determine if support 1044for default initializers in aggregate members is enabled. 1045 1046C++14 digit separators 1047^^^^^^^^^^^^^^^^^^^^^^ 1048 1049Use ``__cpp_digit_separators`` to determine if support for digit separators 1050using single quotes (for instance, ``10'000``) is enabled. At this time, there 1051is no corresponding ``__has_feature`` name 1052 1053C++14 generalized lambda capture 1054^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1055 1056Use ``__has_feature(cxx_init_captures)`` or 1057``__has_extension(cxx_init_captures)`` to determine if support for 1058lambda captures with explicit initializers is enabled 1059(for instance, ``[n(0)] { return ++n; }``). 1060 1061C++14 generic lambdas 1062^^^^^^^^^^^^^^^^^^^^^ 1063 1064Use ``__has_feature(cxx_generic_lambdas)`` or 1065``__has_extension(cxx_generic_lambdas)`` to determine if support for generic 1066(polymorphic) lambdas is enabled 1067(for instance, ``[] (auto x) { return x + 1; }``). 1068 1069C++14 relaxed constexpr 1070^^^^^^^^^^^^^^^^^^^^^^^ 1071 1072Use ``__has_feature(cxx_relaxed_constexpr)`` or 1073``__has_extension(cxx_relaxed_constexpr)`` to determine if variable 1074declarations, local variable modification, and control flow constructs 1075are permitted in ``constexpr`` functions. 1076 1077C++14 return type deduction 1078^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1079 1080Use ``__has_feature(cxx_return_type_deduction)`` or 1081``__has_extension(cxx_return_type_deduction)`` to determine if support 1082for return type deduction for functions (using ``auto`` as a return type) 1083is enabled. 1084 1085C++14 runtime-sized arrays 1086^^^^^^^^^^^^^^^^^^^^^^^^^^ 1087 1088Use ``__has_feature(cxx_runtime_array)`` or 1089``__has_extension(cxx_runtime_array)`` to determine if support 1090for arrays of runtime bound (a restricted form of variable-length arrays) 1091is enabled. 1092Clang's implementation of this feature is incomplete. 1093 1094C++14 variable templates 1095^^^^^^^^^^^^^^^^^^^^^^^^ 1096 1097Use ``__has_feature(cxx_variable_templates)`` or 1098``__has_extension(cxx_variable_templates)`` to determine if support for 1099templated variable declarations is enabled. 1100 1101C11 1102--- 1103 1104The features listed below are part of the C11 standard. As a result, all these 1105features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when 1106compiling C code. Additionally, because these features are all 1107backward-compatible, they are available as extensions in all language modes. 1108 1109C11 alignment specifiers 1110^^^^^^^^^^^^^^^^^^^^^^^^ 1111 1112Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine 1113if support for alignment specifiers using ``_Alignas`` is enabled. 1114 1115Use ``__has_feature(c_alignof)`` or ``__has_extension(c_alignof)`` to determine 1116if support for the ``_Alignof`` keyword is enabled. 1117 1118C11 atomic operations 1119^^^^^^^^^^^^^^^^^^^^^ 1120 1121Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine 1122if support for atomic types using ``_Atomic`` is enabled. Clang also provides 1123:ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement 1124the ``<stdatomic.h>`` operations on ``_Atomic`` types. Use 1125``__has_include(<stdatomic.h>)`` to determine if C11's ``<stdatomic.h>`` header 1126is available. 1127 1128Clang will use the system's ``<stdatomic.h>`` header when one is available, and 1129will otherwise use its own. When using its own, implementations of the atomic 1130operations are provided as macros. In the cases where C11 also requires a real 1131function, this header provides only the declaration of that function (along 1132with a shadowing macro implementation), and you must link to a library which 1133provides a definition of the function if you use it instead of the macro. 1134 1135C11 generic selections 1136^^^^^^^^^^^^^^^^^^^^^^ 1137 1138Use ``__has_feature(c_generic_selections)`` or 1139``__has_extension(c_generic_selections)`` to determine if support for generic 1140selections is enabled. 1141 1142As an extension, the C11 generic selection expression is available in all 1143languages supported by Clang. The syntax is the same as that given in the C11 1144standard. 1145 1146In C, type compatibility is decided according to the rules given in the 1147appropriate standard, but in C++, which lacks the type compatibility rules used 1148in C, types are considered compatible only if they are equivalent. 1149 1150C11 ``_Static_assert()`` 1151^^^^^^^^^^^^^^^^^^^^^^^^ 1152 1153Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)`` 1154to determine if support for compile-time assertions using ``_Static_assert`` is 1155enabled. 1156 1157C11 ``_Thread_local`` 1158^^^^^^^^^^^^^^^^^^^^^ 1159 1160Use ``__has_feature(c_thread_local)`` or ``__has_extension(c_thread_local)`` 1161to determine if support for ``_Thread_local`` variables is enabled. 1162 1163Modules 1164------- 1165 1166Use ``__has_feature(modules)`` to determine if Modules have been enabled. 1167For example, compiling code with ``-fmodules`` enables the use of Modules. 1168 1169More information could be found `here <https://clang.llvm.org/docs/Modules.html>`_. 1170 1171Type Trait Primitives 1172===================== 1173 1174Type trait primitives are special builtin constant expressions that can be used 1175by the standard C++ library to facilitate or simplify the implementation of 1176user-facing type traits in the <type_traits> header. 1177 1178They are not intended to be used directly by user code because they are 1179implementation-defined and subject to change -- as such they're tied closely to 1180the supported set of system headers, currently: 1181 1182* LLVM's own libc++ 1183* GNU libstdc++ 1184* The Microsoft standard C++ library 1185 1186Clang supports the `GNU C++ type traits 1187<https://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the 1188`Microsoft Visual C++ type traits 1189<https://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_, 1190as well as nearly all of the 1191`Embarcadero C++ type traits 1192<http://docwiki.embarcadero.com/RADStudio/Rio/en/Type_Trait_Functions_(C%2B%2B11)_Index>`_. 1193 1194The following type trait primitives are supported by Clang. Those traits marked 1195(C++) provide implementations for type traits specified by the C++ standard; 1196``__X(...)`` has the same semantics and constraints as the corresponding 1197``std::X_t<...>`` or ``std::X_v<...>`` type trait. 1198 1199* ``__array_rank(type)`` (Embarcadero): 1200 Returns the number of levels of array in the type ``type``: 1201 ``0`` if ``type`` is not an array type, and 1202 ``__array_rank(element) + 1`` if ``type`` is an array of ``element``. 1203* ``__array_extent(type, dim)`` (Embarcadero): 1204 The ``dim``'th array bound in the type ``type``, or ``0`` if 1205 ``dim >= __array_rank(type)``. 1206* ``__has_nothrow_assign`` (GNU, Microsoft, Embarcadero): 1207 Deprecated, use ``__is_nothrow_assignable`` instead. 1208* ``__has_nothrow_move_assign`` (GNU, Microsoft): 1209 Deprecated, use ``__is_nothrow_assignable`` instead. 1210* ``__has_nothrow_copy`` (GNU, Microsoft): 1211 Deprecated, use ``__is_nothrow_constructible`` instead. 1212* ``__has_nothrow_constructor`` (GNU, Microsoft): 1213 Deprecated, use ``__is_nothrow_constructible`` instead. 1214* ``__has_trivial_assign`` (GNU, Microsoft, Embarcadero): 1215 Deprecated, use ``__is_trivially_assignable`` instead. 1216* ``__has_trivial_move_assign`` (GNU, Microsoft): 1217 Deprecated, use ``__is_trivially_assignable`` instead. 1218* ``__has_trivial_copy`` (GNU, Microsoft): 1219 Deprecated, use ``__is_trivially_constructible`` instead. 1220* ``__has_trivial_constructor`` (GNU, Microsoft): 1221 Deprecated, use ``__is_trivially_constructible`` instead. 1222* ``__has_trivial_move_constructor`` (GNU, Microsoft): 1223 Deprecated, use ``__is_trivially_constructible`` instead. 1224* ``__has_trivial_destructor`` (GNU, Microsoft, Embarcadero): 1225 Deprecated, use ``__is_trivially_destructible`` instead. 1226* ``__has_unique_object_representations`` (C++, GNU) 1227* ``__has_virtual_destructor`` (C++, GNU, Microsoft, Embarcadero) 1228* ``__is_abstract`` (C++, GNU, Microsoft, Embarcadero) 1229* ``__is_aggregate`` (C++, GNU, Microsoft) 1230* ``__is_arithmetic`` (C++, Embarcadero) 1231* ``__is_array`` (C++, Embarcadero) 1232* ``__is_assignable`` (C++, MSVC 2015) 1233* ``__is_base_of`` (C++, GNU, Microsoft, Embarcadero) 1234* ``__is_class`` (C++, GNU, Microsoft, Embarcadero) 1235* ``__is_complete_type(type)`` (Embarcadero): 1236 Return ``true`` if ``type`` is a complete type. 1237 Warning: this trait is dangerous because it can return different values at 1238 different points in the same program. 1239* ``__is_compound`` (C++, Embarcadero) 1240* ``__is_const`` (C++, Embarcadero) 1241* ``__is_constructible`` (C++, MSVC 2013) 1242* ``__is_convertible`` (C++, Embarcadero) 1243* ``__is_convertible_to`` (Microsoft): 1244 Synonym for ``__is_convertible``. 1245* ``__is_destructible`` (C++, MSVC 2013): 1246 Only available in ``-fms-extensions`` mode. 1247* ``__is_empty`` (C++, GNU, Microsoft, Embarcadero) 1248* ``__is_enum`` (C++, GNU, Microsoft, Embarcadero) 1249* ``__is_final`` (C++, GNU, Microsoft) 1250* ``__is_floating_point`` (C++, Embarcadero) 1251* ``__is_function`` (C++, Embarcadero) 1252* ``__is_fundamental`` (C++, Embarcadero) 1253* ``__is_integral`` (C++, Embarcadero) 1254* ``__is_interface_class`` (Microsoft): 1255 Returns ``false``, even for types defined with ``__interface``. 1256* ``__is_literal`` (Clang): 1257 Synonym for ``__is_literal_type``. 1258* ``__is_literal_type`` (C++, GNU, Microsoft): 1259 Note, the corresponding standard trait was deprecated in C++17 1260 and removed in C++20. 1261* ``__is_lvalue_reference`` (C++, Embarcadero) 1262* ``__is_member_object_pointer`` (C++, Embarcadero) 1263* ``__is_member_function_pointer`` (C++, Embarcadero) 1264* ``__is_member_pointer`` (C++, Embarcadero) 1265* ``__is_nothrow_assignable`` (C++, MSVC 2013) 1266* ``__is_nothrow_constructible`` (C++, MSVC 2013) 1267* ``__is_nothrow_destructible`` (C++, MSVC 2013) 1268 Only available in ``-fms-extensions`` mode. 1269* ``__is_object`` (C++, Embarcadero) 1270* ``__is_pod`` (C++, GNU, Microsoft, Embarcadero): 1271 Note, the corresponding standard trait was deprecated in C++20. 1272* ``__is_pointer`` (C++, Embarcadero) 1273* ``__is_polymorphic`` (C++, GNU, Microsoft, Embarcadero) 1274* ``__is_reference`` (C++, Embarcadero) 1275* ``__is_rvalue_reference`` (C++, Embarcadero) 1276* ``__is_same`` (C++, Embarcadero) 1277* ``__is_same_as`` (GCC): Synonym for ``__is_same``. 1278* ``__is_scalar`` (C++, Embarcadero) 1279* ``__is_sealed`` (Microsoft): 1280 Synonym for ``__is_final``. 1281* ``__is_signed`` (C++, Embarcadero): 1282 Returns false for enumeration types, and returns true for floating-point 1283 types. Note, before Clang 10, returned true for enumeration types if the 1284 underlying type was signed, and returned false for floating-point types. 1285* ``__is_standard_layout`` (C++, GNU, Microsoft, Embarcadero) 1286* ``__is_trivial`` (C++, GNU, Microsoft, Embarcadero) 1287* ``__is_trivially_assignable`` (C++, GNU, Microsoft) 1288* ``__is_trivially_constructible`` (C++, GNU, Microsoft) 1289* ``__is_trivially_copyable`` (C++, GNU, Microsoft) 1290* ``__is_trivially_destructible`` (C++, MSVC 2013) 1291* ``__is_union`` (C++, GNU, Microsoft, Embarcadero) 1292* ``__is_unsigned`` (C++, Embarcadero): 1293 Returns false for enumeration types. Note, before Clang 13, returned true for 1294 enumeration types if the underlying type was unsigned. 1295* ``__is_void`` (C++, Embarcadero) 1296* ``__is_volatile`` (C++, Embarcadero) 1297* ``__reference_binds_to_temporary(T, U)`` (Clang): Determines whether a 1298 reference of type ``T`` bound to an expression of type ``U`` would bind to a 1299 materialized temporary object. If ``T`` is not a reference type the result 1300 is false. Note this trait will also return false when the initialization of 1301 ``T`` from ``U`` is ill-formed. 1302* ``__underlying_type`` (C++, GNU, Microsoft) 1303 1304In addition, the following expression traits are supported: 1305 1306* ``__is_lvalue_expr(e)`` (Embarcadero): 1307 Returns true if ``e`` is an lvalue expression. 1308 Deprecated, use ``__is_lvalue_reference(decltype((e)))`` instead. 1309* ``__is_rvalue_expr(e)`` (Embarcadero): 1310 Returns true if ``e`` is a prvalue expression. 1311 Deprecated, use ``!__is_reference(decltype((e)))`` instead. 1312 1313There are multiple ways to detect support for a type trait ``__X`` in the 1314compiler, depending on the oldest version of Clang you wish to support. 1315 1316* From Clang 10 onwards, ``__has_builtin(__X)`` can be used. 1317* From Clang 6 onwards, ``!__is_identifier(__X)`` can be used. 1318* From Clang 3 onwards, ``__has_feature(X)`` can be used, but only supports 1319 the following traits: 1320 1321 * ``__has_nothrow_assign`` 1322 * ``__has_nothrow_copy`` 1323 * ``__has_nothrow_constructor`` 1324 * ``__has_trivial_assign`` 1325 * ``__has_trivial_copy`` 1326 * ``__has_trivial_constructor`` 1327 * ``__has_trivial_destructor`` 1328 * ``__has_virtual_destructor`` 1329 * ``__is_abstract`` 1330 * ``__is_base_of`` 1331 * ``__is_class`` 1332 * ``__is_constructible`` 1333 * ``__is_convertible_to`` 1334 * ``__is_empty`` 1335 * ``__is_enum`` 1336 * ``__is_final`` 1337 * ``__is_literal`` 1338 * ``__is_standard_layout`` 1339 * ``__is_pod`` 1340 * ``__is_polymorphic`` 1341 * ``__is_sealed`` 1342 * ``__is_trivial`` 1343 * ``__is_trivially_assignable`` 1344 * ``__is_trivially_constructible`` 1345 * ``__is_trivially_copyable`` 1346 * ``__is_union`` 1347 * ``__underlying_type`` 1348 1349A simplistic usage example as might be seen in standard C++ headers follows: 1350 1351.. code-block:: c++ 1352 1353 #if __has_builtin(__is_convertible_to) 1354 template<typename From, typename To> 1355 struct is_convertible_to { 1356 static const bool value = __is_convertible_to(From, To); 1357 }; 1358 #else 1359 // Emulate type trait for compatibility with other compilers. 1360 #endif 1361 1362Blocks 1363====== 1364 1365The syntax and high level language feature description is in 1366:doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for 1367the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`. 1368 1369Query for this feature with ``__has_extension(blocks)``. 1370 1371ASM Goto with Output Constraints 1372================================ 1373 1374In addition to the functionality provided by `GCC's extended 1375assembly <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_, clang 1376supports output constraints with the `goto` form. 1377 1378The goto form of GCC's extended assembly allows the programmer to branch to a C 1379label from within an inline assembly block. Clang extends this behavior by 1380allowing the programmer to use output constraints: 1381 1382.. code-block:: c++ 1383 1384 int foo(int x) { 1385 int y; 1386 asm goto("# %0 %1 %l2" : "=r"(y) : "r"(x) : : err); 1387 return y; 1388 err: 1389 return -1; 1390 } 1391 1392It's important to note that outputs are valid only on the "fallthrough" branch. 1393Using outputs on an indirect branch may result in undefined behavior. For 1394example, in the function above, use of the value assigned to `y` in the `err` 1395block is undefined behavior. 1396 1397Query for this feature with ``__has_extension(gnu_asm_goto_with_outputs)``. 1398 1399Objective-C Features 1400==================== 1401 1402Related result types 1403-------------------- 1404 1405According to Cocoa conventions, Objective-C methods with certain names 1406("``init``", "``alloc``", etc.) always return objects that are an instance of 1407the receiving class's type. Such methods are said to have a "related result 1408type", meaning that a message send to one of these methods will have the same 1409static type as an instance of the receiver class. For example, given the 1410following classes: 1411 1412.. code-block:: objc 1413 1414 @interface NSObject 1415 + (id)alloc; 1416 - (id)init; 1417 @end 1418 1419 @interface NSArray : NSObject 1420 @end 1421 1422and this common initialization pattern 1423 1424.. code-block:: objc 1425 1426 NSArray *array = [[NSArray alloc] init]; 1427 1428the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because 1429``alloc`` implicitly has a related result type. Similarly, the type of the 1430expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a 1431related result type and its receiver is known to have the type ``NSArray *``. 1432If neither ``alloc`` nor ``init`` had a related result type, the expressions 1433would have had type ``id``, as declared in the method signature. 1434 1435A method with a related result type can be declared by using the type 1436``instancetype`` as its result type. ``instancetype`` is a contextual keyword 1437that is only permitted in the result type of an Objective-C method, e.g. 1438 1439.. code-block:: objc 1440 1441 @interface A 1442 + (instancetype)constructAnA; 1443 @end 1444 1445The related result type can also be inferred for some methods. To determine 1446whether a method has an inferred related result type, the first word in the 1447camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered, 1448and the method will have a related result type if its return type is compatible 1449with the type of its class and if: 1450 1451* the first word is "``alloc``" or "``new``", and the method is a class method, 1452 or 1453 1454* the first word is "``autorelease``", "``init``", "``retain``", or "``self``", 1455 and the method is an instance method. 1456 1457If a method with a related result type is overridden by a subclass method, the 1458subclass method must also return a type that is compatible with the subclass 1459type. For example: 1460 1461.. code-block:: objc 1462 1463 @interface NSString : NSObject 1464 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString 1465 @end 1466 1467Related result types only affect the type of a message send or property access 1468via the given method. In all other respects, a method with a related result 1469type is treated the same way as method that returns ``id``. 1470 1471Use ``__has_feature(objc_instancetype)`` to determine whether the 1472``instancetype`` contextual keyword is available. 1473 1474Automatic reference counting 1475---------------------------- 1476 1477Clang provides support for :doc:`automated reference counting 1478<AutomaticReferenceCounting>` in Objective-C, which eliminates the need 1479for manual ``retain``/``release``/``autorelease`` message sends. There are three 1480feature macros associated with automatic reference counting: 1481``__has_feature(objc_arc)`` indicates the availability of automated reference 1482counting in general, while ``__has_feature(objc_arc_weak)`` indicates that 1483automated reference counting also includes support for ``__weak`` pointers to 1484Objective-C objects. ``__has_feature(objc_arc_fields)`` indicates that C structs 1485are allowed to have fields that are pointers to Objective-C objects managed by 1486automatic reference counting. 1487 1488.. _objc-weak: 1489 1490Weak references 1491--------------- 1492 1493Clang supports ARC-style weak and unsafe references in Objective-C even 1494outside of ARC mode. Weak references must be explicitly enabled with 1495the ``-fobjc-weak`` option; use ``__has_feature((objc_arc_weak))`` 1496to test whether they are enabled. Unsafe references are enabled 1497unconditionally. ARC-style weak and unsafe references cannot be used 1498when Objective-C garbage collection is enabled. 1499 1500Except as noted below, the language rules for the ``__weak`` and 1501``__unsafe_unretained`` qualifiers (and the ``weak`` and 1502``unsafe_unretained`` property attributes) are just as laid out 1503in the :doc:`ARC specification <AutomaticReferenceCounting>`. 1504In particular, note that some classes do not support forming weak 1505references to their instances, and note that special care must be 1506taken when storing weak references in memory where initialization 1507and deinitialization are outside the responsibility of the compiler 1508(such as in ``malloc``-ed memory). 1509 1510Loading from a ``__weak`` variable always implicitly retains the 1511loaded value. In non-ARC modes, this retain is normally balanced 1512by an implicit autorelease. This autorelease can be suppressed 1513by performing the load in the receiver position of a ``-retain`` 1514message send (e.g. ``[weakReference retain]``); note that this performs 1515only a single retain (the retain done when primitively loading from 1516the weak reference). 1517 1518For the most part, ``__unsafe_unretained`` in non-ARC modes is just the 1519default behavior of variables and therefore is not needed. However, 1520it does have an effect on the semantics of block captures: normally, 1521copying a block which captures an Objective-C object or block pointer 1522causes the captured pointer to be retained or copied, respectively, 1523but that behavior is suppressed when the captured variable is qualified 1524with ``__unsafe_unretained``. 1525 1526Note that the ``__weak`` qualifier formerly meant the GC qualifier in 1527all non-ARC modes and was silently ignored outside of GC modes. It now 1528means the ARC-style qualifier in all non-GC modes and is no longer 1529allowed if not enabled by either ``-fobjc-arc`` or ``-fobjc-weak``. 1530It is expected that ``-fobjc-weak`` will eventually be enabled by default 1531in all non-GC Objective-C modes. 1532 1533.. _objc-fixed-enum: 1534 1535Enumerations with a fixed underlying type 1536----------------------------------------- 1537 1538Clang provides support for C++11 enumerations with a fixed underlying type 1539within Objective-C. For example, one can write an enumeration type as: 1540 1541.. code-block:: c++ 1542 1543 typedef enum : unsigned char { Red, Green, Blue } Color; 1544 1545This specifies that the underlying type, which is used to store the enumeration 1546value, is ``unsigned char``. 1547 1548Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed 1549underlying types is available in Objective-C. 1550 1551Interoperability with C++11 lambdas 1552----------------------------------- 1553 1554Clang provides interoperability between C++11 lambdas and blocks-based APIs, by 1555permitting a lambda to be implicitly converted to a block pointer with the 1556corresponding signature. For example, consider an API such as ``NSArray``'s 1557array-sorting method: 1558 1559.. code-block:: objc 1560 1561 - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr; 1562 1563``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult 1564(^)(id, id)``, and parameters of this type are generally provided with block 1565literals as arguments. However, one can also use a C++11 lambda so long as it 1566provides the same signature (in this case, accepting two parameters of type 1567``id`` and returning an ``NSComparisonResult``): 1568 1569.. code-block:: objc 1570 1571 NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11", 1572 @"String 02"]; 1573 const NSStringCompareOptions comparisonOptions 1574 = NSCaseInsensitiveSearch | NSNumericSearch | 1575 NSWidthInsensitiveSearch | NSForcedOrderingSearch; 1576 NSLocale *currentLocale = [NSLocale currentLocale]; 1577 NSArray *sorted 1578 = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult { 1579 NSRange string1Range = NSMakeRange(0, [s1 length]); 1580 return [s1 compare:s2 options:comparisonOptions 1581 range:string1Range locale:currentLocale]; 1582 }]; 1583 NSLog(@"sorted: %@", sorted); 1584 1585This code relies on an implicit conversion from the type of the lambda 1586expression (an unnamed, local class type called the *closure type*) to the 1587corresponding block pointer type. The conversion itself is expressed by a 1588conversion operator in that closure type that produces a block pointer with the 1589same signature as the lambda itself, e.g., 1590 1591.. code-block:: objc 1592 1593 operator NSComparisonResult (^)(id, id)() const; 1594 1595This conversion function returns a new block that simply forwards the two 1596parameters to the lambda object (which it captures by copy), then returns the 1597result. The returned block is first copied (with ``Block_copy``) and then 1598autoreleased. As an optimization, if a lambda expression is immediately 1599converted to a block pointer (as in the first example, above), then the block 1600is not copied and autoreleased: rather, it is given the same lifetime as a 1601block literal written at that point in the program, which avoids the overhead 1602of copying a block to the heap in the common case. 1603 1604The conversion from a lambda to a block pointer is only available in 1605Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory 1606management (autorelease). 1607 1608Object Literals and Subscripting 1609-------------------------------- 1610 1611Clang provides support for :doc:`Object Literals and Subscripting 1612<ObjectiveCLiterals>` in Objective-C, which simplifies common Objective-C 1613programming patterns, makes programs more concise, and improves the safety of 1614container creation. There are several feature macros associated with object 1615literals and subscripting: ``__has_feature(objc_array_literals)`` tests the 1616availability of array literals; ``__has_feature(objc_dictionary_literals)`` 1617tests the availability of dictionary literals; 1618``__has_feature(objc_subscripting)`` tests the availability of object 1619subscripting. 1620 1621Objective-C Autosynthesis of Properties 1622--------------------------------------- 1623 1624Clang provides support for autosynthesis of declared properties. Using this 1625feature, clang provides default synthesis of those properties not declared 1626@dynamic and not having user provided backing getter and setter methods. 1627``__has_feature(objc_default_synthesize_properties)`` checks for availability 1628of this feature in version of clang being used. 1629 1630.. _langext-objc-retain-release: 1631 1632Objective-C retaining behavior attributes 1633----------------------------------------- 1634 1635In Objective-C, functions and methods are generally assumed to follow the 1636`Cocoa Memory Management 1637<https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_ 1638conventions for ownership of object arguments and 1639return values. However, there are exceptions, and so Clang provides attributes 1640to allow these exceptions to be documented. This are used by ARC and the 1641`static analyzer <https://clang-analyzer.llvm.org>`_ Some exceptions may be 1642better described using the ``objc_method_family`` attribute instead. 1643 1644**Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``, 1645``ns_returns_autoreleased``, ``cf_returns_retained``, and 1646``cf_returns_not_retained`` attributes can be placed on methods and functions 1647that return Objective-C or CoreFoundation objects. They are commonly placed at 1648the end of a function prototype or method declaration: 1649 1650.. code-block:: objc 1651 1652 id foo() __attribute__((ns_returns_retained)); 1653 1654 - (NSString *)bar:(int)x __attribute__((ns_returns_retained)); 1655 1656The ``*_returns_retained`` attributes specify that the returned object has a +1 1657retain count. The ``*_returns_not_retained`` attributes specify that the return 1658object has a +0 retain count, even if the normal convention for its selector 1659would be +1. ``ns_returns_autoreleased`` specifies that the returned object is 1660+0, but is guaranteed to live at least as long as the next flush of an 1661autorelease pool. 1662 1663**Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on 1664an parameter declaration; they specify that the argument is expected to have a 1665+1 retain count, which will be balanced in some way by the function or method. 1666The ``ns_consumes_self`` attribute can only be placed on an Objective-C 1667method; it specifies that the method expects its ``self`` parameter to have a 1668+1 retain count, which it will balance in some way. 1669 1670.. code-block:: objc 1671 1672 void foo(__attribute__((ns_consumed)) NSString *string); 1673 1674 - (void) bar __attribute__((ns_consumes_self)); 1675 - (void) baz:(id) __attribute__((ns_consumed)) x; 1676 1677Further examples of these attributes are available in the static analyzer's `list of annotations for analysis 1678<https://clang-analyzer.llvm.org/annotations.html#cocoa_mem>`_. 1679 1680Query for these features with ``__has_attribute(ns_consumed)``, 1681``__has_attribute(ns_returns_retained)``, etc. 1682 1683Objective-C @available 1684---------------------- 1685 1686It is possible to use the newest SDK but still build a program that can run on 1687older versions of macOS and iOS by passing ``-mmacosx-version-min=`` / 1688``-miphoneos-version-min=``. 1689 1690Before LLVM 5.0, when calling a function that exists only in the OS that's 1691newer than the target OS (as determined by the minimum deployment version), 1692programmers had to carefully check if the function exists at runtime, using 1693null checks for weakly-linked C functions, ``+class`` for Objective-C classes, 1694and ``-respondsToSelector:`` or ``+instancesRespondToSelector:`` for 1695Objective-C methods. If such a check was missed, the program would compile 1696fine, run fine on newer systems, but crash on older systems. 1697 1698As of LLVM 5.0, ``-Wunguarded-availability`` uses the `availability attributes 1699<https://clang.llvm.org/docs/AttributeReference.html#availability>`_ together 1700with the new ``@available()`` keyword to assist with this issue. 1701When a method that's introduced in the OS newer than the target OS is called, a 1702-Wunguarded-availability warning is emitted if that call is not guarded: 1703 1704.. code-block:: objc 1705 1706 void my_fun(NSSomeClass* var) { 1707 // If fancyNewMethod was added in e.g. macOS 10.12, but the code is 1708 // built with -mmacosx-version-min=10.11, then this unconditional call 1709 // will emit a -Wunguarded-availability warning: 1710 [var fancyNewMethod]; 1711 } 1712 1713To fix the warning and to avoid the crash on macOS 10.11, wrap it in 1714``if(@available())``: 1715 1716.. code-block:: objc 1717 1718 void my_fun(NSSomeClass* var) { 1719 if (@available(macOS 10.12, *)) { 1720 [var fancyNewMethod]; 1721 } else { 1722 // Put fallback behavior for old macOS versions (and for non-mac 1723 // platforms) here. 1724 } 1725 } 1726 1727The ``*`` is required and means that platforms not explicitly listed will take 1728the true branch, and the compiler will emit ``-Wunguarded-availability`` 1729warnings for unlisted platforms based on those platform's deployment target. 1730More than one platform can be listed in ``@available()``: 1731 1732.. code-block:: objc 1733 1734 void my_fun(NSSomeClass* var) { 1735 if (@available(macOS 10.12, iOS 10, *)) { 1736 [var fancyNewMethod]; 1737 } 1738 } 1739 1740If the caller of ``my_fun()`` already checks that ``my_fun()`` is only called 1741on 10.12, then add an `availability attribute 1742<https://clang.llvm.org/docs/AttributeReference.html#availability>`_ to it, 1743which will also suppress the warning and require that calls to my_fun() are 1744checked: 1745 1746.. code-block:: objc 1747 1748 API_AVAILABLE(macos(10.12)) void my_fun(NSSomeClass* var) { 1749 [var fancyNewMethod]; // Now ok. 1750 } 1751 1752``@available()`` is only available in Objective-C code. To use the feature 1753in C and C++ code, use the ``__builtin_available()`` spelling instead. 1754 1755If existing code uses null checks or ``-respondsToSelector:``, it should 1756be changed to use ``@available()`` (or ``__builtin_available``) instead. 1757 1758``-Wunguarded-availability`` is disabled by default, but 1759``-Wunguarded-availability-new``, which only emits this warning for APIs 1760that have been introduced in macOS >= 10.13, iOS >= 11, watchOS >= 4 and 1761tvOS >= 11, is enabled by default. 1762 1763.. _langext-overloading: 1764 1765Objective-C++ ABI: protocol-qualifier mangling of parameters 1766------------------------------------------------------------ 1767 1768Starting with LLVM 3.4, Clang produces a new mangling for parameters whose 1769type is a qualified-``id`` (e.g., ``id<Foo>``). This mangling allows such 1770parameters to be differentiated from those with the regular unqualified ``id`` 1771type. 1772 1773This was a non-backward compatible mangling change to the ABI. This change 1774allows proper overloading, and also prevents mangling conflicts with template 1775parameters of protocol-qualified type. 1776 1777Query the presence of this new mangling with 1778``__has_feature(objc_protocol_qualifier_mangling)``. 1779 1780Initializer lists for complex numbers in C 1781========================================== 1782 1783clang supports an extension which allows the following in C: 1784 1785.. code-block:: c++ 1786 1787 #include <math.h> 1788 #include <complex.h> 1789 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf) 1790 1791This construct is useful because there is no way to separately initialize the 1792real and imaginary parts of a complex variable in standard C, given that clang 1793does not support ``_Imaginary``. (Clang also supports the ``__real__`` and 1794``__imag__`` extensions from gcc, which help in some cases, but are not usable 1795in static initializers.) 1796 1797Note that this extension does not allow eliding the braces; the meaning of the 1798following two lines is different: 1799 1800.. code-block:: c++ 1801 1802 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1) 1803 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0) 1804 1805This extension also works in C++ mode, as far as that goes, but does not apply 1806to the C++ ``std::complex``. (In C++11, list initialization allows the same 1807syntax to be used with ``std::complex`` with the same meaning.) 1808 1809For GCC compatibility, ``__builtin_complex(re, im)`` can also be used to 1810construct a complex number from the given real and imaginary components. 1811 1812OpenCL Features 1813=============== 1814 1815Clang supports internal OpenCL extensions documented below. 1816 1817``__cl_clang_bitfields`` 1818-------------------------------- 1819 1820With this extension it is possible to enable bitfields in structs 1821or unions using the OpenCL extension pragma mechanism detailed in 1822`the OpenCL Extension Specification, section 1.2 1823<https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_. 1824 1825Use of bitfields in OpenCL kernels can result in reduced portability as struct 1826layout is not guaranteed to be consistent when compiled by different compilers. 1827If structs with bitfields are used as kernel function parameters, it can result 1828in incorrect functionality when the layout is different between the host and 1829device code. 1830 1831**Example of Use**: 1832 1833.. code-block:: c++ 1834 1835 #pragma OPENCL EXTENSION __cl_clang_bitfields : enable 1836 struct with_bitfield { 1837 unsigned int i : 5; // compiled - no diagnostic generated 1838 }; 1839 1840 #pragma OPENCL EXTENSION __cl_clang_bitfields : disable 1841 struct without_bitfield { 1842 unsigned int i : 5; // error - bitfields are not supported 1843 }; 1844 1845``__cl_clang_function_pointers`` 1846-------------------------------- 1847 1848With this extension it is possible to enable various language features that 1849are relying on function pointers using regular OpenCL extension pragma 1850mechanism detailed in `the OpenCL Extension Specification, 1851section 1.2 1852<https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_. 1853 1854In C++ for OpenCL this also enables: 1855 1856- Use of member function pointers; 1857 1858- Unrestricted use of references to functions; 1859 1860- Virtual member functions. 1861 1862Such functionality is not conformant and does not guarantee to compile 1863correctly in any circumstances. It can be used if: 1864 1865- the kernel source does not contain call expressions to (member-) function 1866 pointers, or virtual functions. For example this extension can be used in 1867 metaprogramming algorithms to be able to specify/detect types generically. 1868 1869- the generated kernel binary does not contain indirect calls because they 1870 are eliminated using compiler optimizations e.g. devirtualization. 1871 1872- the selected target supports the function pointer like functionality e.g. 1873 most CPU targets. 1874 1875**Example of Use**: 1876 1877.. code-block:: c++ 1878 1879 #pragma OPENCL EXTENSION __cl_clang_function_pointers : enable 1880 void foo() 1881 { 1882 void (*fp)(); // compiled - no diagnostic generated 1883 } 1884 1885 #pragma OPENCL EXTENSION __cl_clang_function_pointers : disable 1886 void bar() 1887 { 1888 void (*fp)(); // error - pointers to function are not allowed 1889 } 1890 1891``__cl_clang_variadic_functions`` 1892--------------------------------- 1893 1894With this extension it is possible to enable variadic arguments in functions 1895using regular OpenCL extension pragma mechanism detailed in `the OpenCL 1896Extension Specification, section 1.2 1897<https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_. 1898 1899This is not conformant behavior and it can only be used portably when the 1900functions with variadic prototypes do not get generated in binary e.g. the 1901variadic prototype is used to specify a function type with any number of 1902arguments in metaprogramming algorithms in C++ for OpenCL. 1903 1904This extensions can also be used when the kernel code is intended for targets 1905supporting the variadic arguments e.g. majority of CPU targets. 1906 1907**Example of Use**: 1908 1909.. code-block:: c++ 1910 1911 #pragma OPENCL EXTENSION __cl_clang_variadic_functions : enable 1912 void foo(int a, ...); // compiled - no diagnostic generated 1913 1914 #pragma OPENCL EXTENSION __cl_clang_variadic_functions : disable 1915 void bar(int a, ...); // error - variadic prototype is not allowed 1916 1917``__cl_clang_non_portable_kernel_param_types`` 1918---------------------------------------------- 1919 1920With this extension it is possible to enable the use of some restricted types 1921in kernel parameters specified in `C++ for OpenCL v1.0 s2.4 1922<https://www.khronos.org/opencl/assets/CXX_for_OpenCL.html#kernel_function>`_. 1923The restrictions can be relaxed using regular OpenCL extension pragma mechanism 1924detailed in `the OpenCL Extension Specification, section 1.2 1925<https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_. 1926 1927This is not a conformant behavior and it can only be used when the 1928kernel arguments are not accessed on the host side or the data layout/size 1929between the host and device is known to be compatible. 1930 1931**Example of Use**: 1932 1933.. code-block:: c++ 1934 1935 // Plain Old Data type. 1936 struct Pod { 1937 int a; 1938 int b; 1939 }; 1940 1941 // Not POD type because of the constructor. 1942 // Standard layout type because there is only one access control. 1943 struct OnlySL { 1944 int a; 1945 int b; 1946 NotPod() : a(0), b(0) {} 1947 }; 1948 1949 // Not standard layout type because of two different access controls. 1950 struct NotSL { 1951 int a; 1952 private: 1953 int b; 1954 } 1955 1956 kernel void kernel_main( 1957 Pod a, 1958 #pragma OPENCL EXTENSION __cl_clang_non_portable_kernel_param_types : enable 1959 OnlySL b, 1960 global NotSL *c, 1961 #pragma OPENCL EXTENSION __cl_clang_non_portable_kernel_param_types : disable 1962 global OnlySL *d, 1963 ); 1964 1965Remove address space builtin function 1966------------------------------------- 1967 1968``__remove_address_space`` allows to derive types in C++ for OpenCL 1969that have address space qualifiers removed. This utility only affects 1970address space qualifiers, therefore, other type qualifiers such as 1971``const`` or ``volatile`` remain unchanged. 1972 1973**Example of Use**: 1974 1975.. code-block:: c++ 1976 1977 template<typename T> 1978 void foo(T *par){ 1979 T var1; // error - local function variable with global address space 1980 __private T var2; // error - conflicting address space qualifiers 1981 __private __remove_address_space<T>::type var3; // var3 is __private int 1982 } 1983 1984 void bar(){ 1985 __global int* ptr; 1986 foo(ptr); 1987 } 1988 1989Legacy 1.x atomics with generic address space 1990--------------------------------------------- 1991 1992Clang allows use of atomic functions from the OpenCL 1.x standards 1993with the generic address space pointer in C++ for OpenCL mode. 1994 1995This is a non-portable feature and might not be supported by all 1996targets. 1997 1998**Example of Use**: 1999 2000.. code-block:: c++ 2001 2002 void foo(__generic volatile unsigned int* a) { 2003 atomic_add(a, 1); 2004 } 2005 2006Builtin Functions 2007================= 2008 2009Clang supports a number of builtin library functions with the same syntax as 2010GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``, 2011``__builtin_choose_expr``, ``__builtin_types_compatible_p``, 2012``__builtin_assume_aligned``, ``__sync_fetch_and_add``, etc. In addition to 2013the GCC builtins, Clang supports a number of builtins that GCC does not, which 2014are listed here. 2015 2016Please note that Clang does not and will not support all of the GCC builtins 2017for vector operations. Instead of using builtins, you should use the functions 2018defined in target-specific header files like ``<xmmintrin.h>``, which define 2019portable wrappers for these. Many of the Clang versions of these functions are 2020implemented directly in terms of :ref:`extended vector support 2021<langext-vectors>` instead of builtins, in order to reduce the number of 2022builtins that we need to implement. 2023 2024.. _langext-__builtin_assume: 2025 2026``__builtin_assume`` 2027------------------------------ 2028 2029``__builtin_assume`` is used to provide the optimizer with a boolean 2030invariant that is defined to be true. 2031 2032**Syntax**: 2033 2034.. code-block:: c++ 2035 2036 __builtin_assume(bool) 2037 2038**Example of Use**: 2039 2040.. code-block:: c++ 2041 2042 int foo(int x) { 2043 __builtin_assume(x != 0); 2044 2045 // The optimizer may short-circuit this check using the invariant. 2046 if (x == 0) 2047 return do_something(); 2048 2049 return do_something_else(); 2050 } 2051 2052**Description**: 2053 2054The boolean argument to this function is defined to be true. The optimizer may 2055analyze the form of the expression provided as the argument and deduce from 2056that information used to optimize the program. If the condition is violated 2057during execution, the behavior is undefined. The argument itself is never 2058evaluated, so any side effects of the expression will be discarded. 2059 2060Query for this feature with ``__has_builtin(__builtin_assume)``. 2061 2062``__builtin_readcyclecounter`` 2063------------------------------ 2064 2065``__builtin_readcyclecounter`` is used to access the cycle counter register (or 2066a similar low-latency, high-accuracy clock) on those targets that support it. 2067 2068**Syntax**: 2069 2070.. code-block:: c++ 2071 2072 __builtin_readcyclecounter() 2073 2074**Example of Use**: 2075 2076.. code-block:: c++ 2077 2078 unsigned long long t0 = __builtin_readcyclecounter(); 2079 do_something(); 2080 unsigned long long t1 = __builtin_readcyclecounter(); 2081 unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow 2082 2083**Description**: 2084 2085The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value, 2086which may be either global or process/thread-specific depending on the target. 2087As the backing counters often overflow quickly (on the order of seconds) this 2088should only be used for timing small intervals. When not supported by the 2089target, the return value is always zero. This builtin takes no arguments and 2090produces an unsigned long long result. 2091 2092Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``. Note 2093that even if present, its use may depend on run-time privilege or other OS 2094controlled state. 2095 2096``__builtin_dump_struct`` 2097------------------------- 2098 2099**Syntax**: 2100 2101.. code-block:: c++ 2102 2103 __builtin_dump_struct(&some_struct, &some_printf_func); 2104 2105**Examples**: 2106 2107.. code-block:: c++ 2108 2109 struct S { 2110 int x, y; 2111 float f; 2112 struct T { 2113 int i; 2114 } t; 2115 }; 2116 2117 void func(struct S *s) { 2118 __builtin_dump_struct(s, &printf); 2119 } 2120 2121Example output: 2122 2123.. code-block:: none 2124 2125 struct S { 2126 int i : 100 2127 int j : 42 2128 float f : 3.14159 2129 struct T t : struct T { 2130 int i : 1997 2131 } 2132 } 2133 2134**Description**: 2135 2136The '``__builtin_dump_struct``' function is used to print the fields of a simple 2137structure and their values for debugging purposes. The builtin accepts a pointer 2138to a structure to dump the fields of, and a pointer to a formatted output 2139function whose signature must be: ``int (*)(const char *, ...)`` and must 2140support the format specifiers used by ``printf()``. 2141 2142.. _langext-__builtin_shufflevector: 2143 2144``__builtin_shufflevector`` 2145--------------------------- 2146 2147``__builtin_shufflevector`` is used to express generic vector 2148permutation/shuffle/swizzle operations. This builtin is also very important 2149for the implementation of various target-specific header files like 2150``<xmmintrin.h>``. 2151 2152**Syntax**: 2153 2154.. code-block:: c++ 2155 2156 __builtin_shufflevector(vec1, vec2, index1, index2, ...) 2157 2158**Examples**: 2159 2160.. code-block:: c++ 2161 2162 // identity operation - return 4-element vector v1. 2163 __builtin_shufflevector(v1, v1, 0, 1, 2, 3) 2164 2165 // "Splat" element 0 of V1 into a 4-element result. 2166 __builtin_shufflevector(V1, V1, 0, 0, 0, 0) 2167 2168 // Reverse 4-element vector V1. 2169 __builtin_shufflevector(V1, V1, 3, 2, 1, 0) 2170 2171 // Concatenate every other element of 4-element vectors V1 and V2. 2172 __builtin_shufflevector(V1, V2, 0, 2, 4, 6) 2173 2174 // Concatenate every other element of 8-element vectors V1 and V2. 2175 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14) 2176 2177 // Shuffle v1 with some elements being undefined 2178 __builtin_shufflevector(v1, v1, 3, -1, 1, -1) 2179 2180**Description**: 2181 2182The first two arguments to ``__builtin_shufflevector`` are vectors that have 2183the same element type. The remaining arguments are a list of integers that 2184specify the elements indices of the first two vectors that should be extracted 2185and returned in a new vector. These element indices are numbered sequentially 2186starting with the first vector, continuing into the second vector. Thus, if 2187``vec1`` is a 4-element vector, index 5 would refer to the second element of 2188``vec2``. An index of -1 can be used to indicate that the corresponding element 2189in the returned vector is a don't care and can be optimized by the backend. 2190 2191The result of ``__builtin_shufflevector`` is a vector with the same element 2192type as ``vec1``/``vec2`` but that has an element count equal to the number of 2193indices specified. 2194 2195Query for this feature with ``__has_builtin(__builtin_shufflevector)``. 2196 2197.. _langext-__builtin_convertvector: 2198 2199``__builtin_convertvector`` 2200--------------------------- 2201 2202``__builtin_convertvector`` is used to express generic vector 2203type-conversion operations. The input vector and the output vector 2204type must have the same number of elements. 2205 2206**Syntax**: 2207 2208.. code-block:: c++ 2209 2210 __builtin_convertvector(src_vec, dst_vec_type) 2211 2212**Examples**: 2213 2214.. code-block:: c++ 2215 2216 typedef double vector4double __attribute__((__vector_size__(32))); 2217 typedef float vector4float __attribute__((__vector_size__(16))); 2218 typedef short vector4short __attribute__((__vector_size__(8))); 2219 vector4float vf; vector4short vs; 2220 2221 // convert from a vector of 4 floats to a vector of 4 doubles. 2222 __builtin_convertvector(vf, vector4double) 2223 // equivalent to: 2224 (vector4double) { (double) vf[0], (double) vf[1], (double) vf[2], (double) vf[3] } 2225 2226 // convert from a vector of 4 shorts to a vector of 4 floats. 2227 __builtin_convertvector(vs, vector4float) 2228 // equivalent to: 2229 (vector4float) { (float) vs[0], (float) vs[1], (float) vs[2], (float) vs[3] } 2230 2231**Description**: 2232 2233The first argument to ``__builtin_convertvector`` is a vector, and the second 2234argument is a vector type with the same number of elements as the first 2235argument. 2236 2237The result of ``__builtin_convertvector`` is a vector with the same element 2238type as the second argument, with a value defined in terms of the action of a 2239C-style cast applied to each element of the first argument. 2240 2241Query for this feature with ``__has_builtin(__builtin_convertvector)``. 2242 2243``__builtin_bitreverse`` 2244------------------------ 2245 2246* ``__builtin_bitreverse8`` 2247* ``__builtin_bitreverse16`` 2248* ``__builtin_bitreverse32`` 2249* ``__builtin_bitreverse64`` 2250 2251**Syntax**: 2252 2253.. code-block:: c++ 2254 2255 __builtin_bitreverse32(x) 2256 2257**Examples**: 2258 2259.. code-block:: c++ 2260 2261 uint8_t rev_x = __builtin_bitreverse8(x); 2262 uint16_t rev_x = __builtin_bitreverse16(x); 2263 uint32_t rev_y = __builtin_bitreverse32(y); 2264 uint64_t rev_z = __builtin_bitreverse64(z); 2265 2266**Description**: 2267 2268The '``__builtin_bitreverse``' family of builtins is used to reverse 2269the bitpattern of an integer value; for example ``0b10110110`` becomes 2270``0b01101101``. These builtins can be used within constant expressions. 2271 2272``__builtin_rotateleft`` 2273------------------------ 2274 2275* ``__builtin_rotateleft8`` 2276* ``__builtin_rotateleft16`` 2277* ``__builtin_rotateleft32`` 2278* ``__builtin_rotateleft64`` 2279 2280**Syntax**: 2281 2282.. code-block:: c++ 2283 2284 __builtin_rotateleft32(x, y) 2285 2286**Examples**: 2287 2288.. code-block:: c++ 2289 2290 uint8_t rot_x = __builtin_rotateleft8(x, y); 2291 uint16_t rot_x = __builtin_rotateleft16(x, y); 2292 uint32_t rot_x = __builtin_rotateleft32(x, y); 2293 uint64_t rot_x = __builtin_rotateleft64(x, y); 2294 2295**Description**: 2296 2297The '``__builtin_rotateleft``' family of builtins is used to rotate 2298the bits in the first argument by the amount in the second argument. 2299For example, ``0b10000110`` rotated left by 11 becomes ``0b00110100``. 2300The shift value is treated as an unsigned amount modulo the size of 2301the arguments. Both arguments and the result have the bitwidth specified 2302by the name of the builtin. These builtins can be used within constant 2303expressions. 2304 2305``__builtin_rotateright`` 2306------------------------- 2307 2308* ``__builtin_rotateright8`` 2309* ``__builtin_rotateright16`` 2310* ``__builtin_rotateright32`` 2311* ``__builtin_rotateright64`` 2312 2313**Syntax**: 2314 2315.. code-block:: c++ 2316 2317 __builtin_rotateright32(x, y) 2318 2319**Examples**: 2320 2321.. code-block:: c++ 2322 2323 uint8_t rot_x = __builtin_rotateright8(x, y); 2324 uint16_t rot_x = __builtin_rotateright16(x, y); 2325 uint32_t rot_x = __builtin_rotateright32(x, y); 2326 uint64_t rot_x = __builtin_rotateright64(x, y); 2327 2328**Description**: 2329 2330The '``__builtin_rotateright``' family of builtins is used to rotate 2331the bits in the first argument by the amount in the second argument. 2332For example, ``0b10000110`` rotated right by 3 becomes ``0b11010000``. 2333The shift value is treated as an unsigned amount modulo the size of 2334the arguments. Both arguments and the result have the bitwidth specified 2335by the name of the builtin. These builtins can be used within constant 2336expressions. 2337 2338``__builtin_unreachable`` 2339------------------------- 2340 2341``__builtin_unreachable`` is used to indicate that a specific point in the 2342program cannot be reached, even if the compiler might otherwise think it can. 2343This is useful to improve optimization and eliminates certain warnings. For 2344example, without the ``__builtin_unreachable`` in the example below, the 2345compiler assumes that the inline asm can fall through and prints a "function 2346declared '``noreturn``' should not return" warning. 2347 2348**Syntax**: 2349 2350.. code-block:: c++ 2351 2352 __builtin_unreachable() 2353 2354**Example of use**: 2355 2356.. code-block:: c++ 2357 2358 void myabort(void) __attribute__((noreturn)); 2359 void myabort(void) { 2360 asm("int3"); 2361 __builtin_unreachable(); 2362 } 2363 2364**Description**: 2365 2366The ``__builtin_unreachable()`` builtin has completely undefined behavior. 2367Since it has undefined behavior, it is a statement that it is never reached and 2368the optimizer can take advantage of this to produce better code. This builtin 2369takes no arguments and produces a void result. 2370 2371Query for this feature with ``__has_builtin(__builtin_unreachable)``. 2372 2373``__builtin_unpredictable`` 2374--------------------------- 2375 2376``__builtin_unpredictable`` is used to indicate that a branch condition is 2377unpredictable by hardware mechanisms such as branch prediction logic. 2378 2379**Syntax**: 2380 2381.. code-block:: c++ 2382 2383 __builtin_unpredictable(long long) 2384 2385**Example of use**: 2386 2387.. code-block:: c++ 2388 2389 if (__builtin_unpredictable(x > 0)) { 2390 foo(); 2391 } 2392 2393**Description**: 2394 2395The ``__builtin_unpredictable()`` builtin is expected to be used with control 2396flow conditions such as in ``if`` and ``switch`` statements. 2397 2398Query for this feature with ``__has_builtin(__builtin_unpredictable)``. 2399 2400``__sync_swap`` 2401--------------- 2402 2403``__sync_swap`` is used to atomically swap integers or pointers in memory. 2404 2405**Syntax**: 2406 2407.. code-block:: c++ 2408 2409 type __sync_swap(type *ptr, type value, ...) 2410 2411**Example of Use**: 2412 2413.. code-block:: c++ 2414 2415 int old_value = __sync_swap(&value, new_value); 2416 2417**Description**: 2418 2419The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of 2420atomic intrinsics to allow code to atomically swap the current value with the 2421new value. More importantly, it helps developers write more efficient and 2422correct code by avoiding expensive loops around 2423``__sync_bool_compare_and_swap()`` or relying on the platform specific 2424implementation details of ``__sync_lock_test_and_set()``. The 2425``__sync_swap()`` builtin is a full barrier. 2426 2427``__builtin_addressof`` 2428----------------------- 2429 2430``__builtin_addressof`` performs the functionality of the built-in ``&`` 2431operator, ignoring any ``operator&`` overload. This is useful in constant 2432expressions in C++11, where there is no other way to take the address of an 2433object that overloads ``operator&``. 2434 2435**Example of use**: 2436 2437.. code-block:: c++ 2438 2439 template<typename T> constexpr T *addressof(T &value) { 2440 return __builtin_addressof(value); 2441 } 2442 2443``__builtin_operator_new`` and ``__builtin_operator_delete`` 2444------------------------------------------------------------ 2445 2446A call to ``__builtin_operator_new(args)`` is exactly the same as a call to 2447``::operator new(args)``, except that it allows certain optimizations 2448that the C++ standard does not permit for a direct function call to 2449``::operator new`` (in particular, removing ``new`` / ``delete`` pairs and 2450merging allocations), and that the call is required to resolve to a 2451`replaceable global allocation function 2452<https://en.cppreference.com/w/cpp/memory/new/operator_new>`_. 2453 2454Likewise, ``__builtin_operator_delete`` is exactly the same as a call to 2455``::operator delete(args)``, except that it permits optimizations 2456and that the call is required to resolve to a 2457`replaceable global deallocation function 2458<https://en.cppreference.com/w/cpp/memory/new/operator_delete>`_. 2459 2460These builtins are intended for use in the implementation of ``std::allocator`` 2461and other similar allocation libraries, and are only available in C++. 2462 2463Query for this feature with ``__has_builtin(__builtin_operator_new)`` or 2464``__has_builtin(__builtin_operator_delete)``: 2465 2466 * If the value is at least ``201802L``, the builtins behave as described above. 2467 2468 * If the value is non-zero, the builtins may not support calling arbitrary 2469 replaceable global (de)allocation functions, but do support calling at least 2470 ``::operator new(size_t)`` and ``::operator delete(void*)``. 2471 2472``__builtin_preserve_access_index`` 2473----------------------------------- 2474 2475``__builtin_preserve_access_index`` specifies a code section where 2476array subscript access and structure/union member access are relocatable 2477under bpf compile-once run-everywhere framework. Debuginfo (typically 2478with ``-g``) is needed, otherwise, the compiler will exit with an error. 2479The return type for the intrinsic is the same as the type of the 2480argument. 2481 2482**Syntax**: 2483 2484.. code-block:: c 2485 2486 type __builtin_preserve_access_index(type arg) 2487 2488**Example of Use**: 2489 2490.. code-block:: c 2491 2492 struct t { 2493 int i; 2494 int j; 2495 union { 2496 int a; 2497 int b; 2498 } c[4]; 2499 }; 2500 struct t *v = ...; 2501 int *pb =__builtin_preserve_access_index(&v->c[3].b); 2502 __builtin_preserve_access_index(v->j); 2503 2504``__builtin_sycl_unique_stable_name`` 2505------------------------------------- 2506 2507``__builtin_sycl_unique_stable_name()`` is a builtin that takes a type and 2508produces a string literal containing a unique name for the type that is stable 2509across split compilations, mainly to support SYCL/Data Parallel C++ language. 2510 2511In cases where the split compilation needs to share a unique token for a type 2512across the boundary (such as in an offloading situation), this name can be used 2513for lookup purposes, such as in the SYCL Integration Header. 2514 2515The value of this builtin is computed entirely at compile time, so it can be 2516used in constant expressions. This value encodes lambda functions based on a 2517stable numbering order in which they appear in their local declaration contexts. 2518Once this builtin is evaluated in a constexpr context, it is erroneous to use 2519it in an instantiation which changes its value. 2520 2521In order to produce the unique name, the current implementation of the bultin 2522uses Itanium mangling even if the host compilation uses a different name 2523mangling scheme at runtime. The mangler marks all the lambdas required to name 2524the SYCL kernel and emits a stable local ordering of the respective lambdas. 2525The resulting pattern is demanglable. When non-lambda types are passed to the 2526builtin, the mangler emits their usual pattern without any special treatment. 2527 2528**Syntax**: 2529 2530.. code-block:: c 2531 2532 // Computes a unique stable name for the given type. 2533 constexpr const char * __builtin_sycl_unique_stable_name( type-id ); 2534 2535Multiprecision Arithmetic Builtins 2536---------------------------------- 2537 2538Clang provides a set of builtins which expose multiprecision arithmetic in a 2539manner amenable to C. They all have the following form: 2540 2541.. code-block:: c 2542 2543 unsigned x = ..., y = ..., carryin = ..., carryout; 2544 unsigned sum = __builtin_addc(x, y, carryin, &carryout); 2545 2546Thus one can form a multiprecision addition chain in the following manner: 2547 2548.. code-block:: c 2549 2550 unsigned *x, *y, *z, carryin=0, carryout; 2551 z[0] = __builtin_addc(x[0], y[0], carryin, &carryout); 2552 carryin = carryout; 2553 z[1] = __builtin_addc(x[1], y[1], carryin, &carryout); 2554 carryin = carryout; 2555 z[2] = __builtin_addc(x[2], y[2], carryin, &carryout); 2556 carryin = carryout; 2557 z[3] = __builtin_addc(x[3], y[3], carryin, &carryout); 2558 2559The complete list of builtins are: 2560 2561.. code-block:: c 2562 2563 unsigned char __builtin_addcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout); 2564 unsigned short __builtin_addcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout); 2565 unsigned __builtin_addc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout); 2566 unsigned long __builtin_addcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout); 2567 unsigned long long __builtin_addcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout); 2568 unsigned char __builtin_subcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout); 2569 unsigned short __builtin_subcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout); 2570 unsigned __builtin_subc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout); 2571 unsigned long __builtin_subcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout); 2572 unsigned long long __builtin_subcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout); 2573 2574Checked Arithmetic Builtins 2575--------------------------- 2576 2577Clang provides a set of builtins that implement checked arithmetic for security 2578critical applications in a manner that is fast and easily expressible in C. As 2579an example of their usage: 2580 2581.. code-block:: c 2582 2583 errorcode_t security_critical_application(...) { 2584 unsigned x, y, result; 2585 ... 2586 if (__builtin_mul_overflow(x, y, &result)) 2587 return kErrorCodeHackers; 2588 ... 2589 use_multiply(result); 2590 ... 2591 } 2592 2593Clang provides the following checked arithmetic builtins: 2594 2595.. code-block:: c 2596 2597 bool __builtin_add_overflow (type1 x, type2 y, type3 *sum); 2598 bool __builtin_sub_overflow (type1 x, type2 y, type3 *diff); 2599 bool __builtin_mul_overflow (type1 x, type2 y, type3 *prod); 2600 bool __builtin_uadd_overflow (unsigned x, unsigned y, unsigned *sum); 2601 bool __builtin_uaddl_overflow (unsigned long x, unsigned long y, unsigned long *sum); 2602 bool __builtin_uaddll_overflow(unsigned long long x, unsigned long long y, unsigned long long *sum); 2603 bool __builtin_usub_overflow (unsigned x, unsigned y, unsigned *diff); 2604 bool __builtin_usubl_overflow (unsigned long x, unsigned long y, unsigned long *diff); 2605 bool __builtin_usubll_overflow(unsigned long long x, unsigned long long y, unsigned long long *diff); 2606 bool __builtin_umul_overflow (unsigned x, unsigned y, unsigned *prod); 2607 bool __builtin_umull_overflow (unsigned long x, unsigned long y, unsigned long *prod); 2608 bool __builtin_umulll_overflow(unsigned long long x, unsigned long long y, unsigned long long *prod); 2609 bool __builtin_sadd_overflow (int x, int y, int *sum); 2610 bool __builtin_saddl_overflow (long x, long y, long *sum); 2611 bool __builtin_saddll_overflow(long long x, long long y, long long *sum); 2612 bool __builtin_ssub_overflow (int x, int y, int *diff); 2613 bool __builtin_ssubl_overflow (long x, long y, long *diff); 2614 bool __builtin_ssubll_overflow(long long x, long long y, long long *diff); 2615 bool __builtin_smul_overflow (int x, int y, int *prod); 2616 bool __builtin_smull_overflow (long x, long y, long *prod); 2617 bool __builtin_smulll_overflow(long long x, long long y, long long *prod); 2618 2619Each builtin performs the specified mathematical operation on the 2620first two arguments and stores the result in the third argument. If 2621possible, the result will be equal to mathematically-correct result 2622and the builtin will return 0. Otherwise, the builtin will return 26231 and the result will be equal to the unique value that is equivalent 2624to the mathematically-correct result modulo two raised to the *k* 2625power, where *k* is the number of bits in the result type. The 2626behavior of these builtins is well-defined for all argument values. 2627 2628The first three builtins work generically for operands of any integer type, 2629including boolean types. The operands need not have the same type as each 2630other, or as the result. The other builtins may implicitly promote or 2631convert their operands before performing the operation. 2632 2633Query for this feature with ``__has_builtin(__builtin_add_overflow)``, etc. 2634 2635Floating point builtins 2636--------------------------------------- 2637 2638``__builtin_canonicalize`` 2639-------------------------- 2640 2641.. code-block:: c 2642 2643 double __builtin_canonicalize(double); 2644 float __builtin_canonicalizef(float); 2645 long double__builtin_canonicalizel(long double); 2646 2647Returns the platform specific canonical encoding of a floating point 2648number. This canonicalization is useful for implementing certain 2649numeric primitives such as frexp. See `LLVM canonicalize intrinsic 2650<https://llvm.org/docs/LangRef.html#llvm-canonicalize-intrinsic>`_ for 2651more information on the semantics. 2652 2653String builtins 2654--------------- 2655 2656Clang provides constant expression evaluation support for builtins forms of 2657the following functions from the C standard library headers 2658``<string.h>`` and ``<wchar.h>``: 2659 2660* ``memchr`` 2661* ``memcmp`` (and its deprecated BSD / POSIX alias ``bcmp``) 2662* ``strchr`` 2663* ``strcmp`` 2664* ``strlen`` 2665* ``strncmp`` 2666* ``wcschr`` 2667* ``wcscmp`` 2668* ``wcslen`` 2669* ``wcsncmp`` 2670* ``wmemchr`` 2671* ``wmemcmp`` 2672 2673In each case, the builtin form has the name of the C library function prefixed 2674by ``__builtin_``. Example: 2675 2676.. code-block:: c 2677 2678 void *p = __builtin_memchr("foobar", 'b', 5); 2679 2680In addition to the above, one further builtin is provided: 2681 2682.. code-block:: c 2683 2684 char *__builtin_char_memchr(const char *haystack, int needle, size_t size); 2685 2686``__builtin_char_memchr(a, b, c)`` is identical to 2687``(char*)__builtin_memchr(a, b, c)`` except that its use is permitted within 2688constant expressions in C++11 onwards (where a cast from ``void*`` to ``char*`` 2689is disallowed in general). 2690 2691Constant evaluation support for the ``__builtin_mem*`` functions is provided 2692only for arrays of ``char``, ``signed char``, ``unsigned char``, or ``char8_t``, 2693despite these functions accepting an argument of type ``const void*``. 2694 2695Support for constant expression evaluation for the above builtins can be detected 2696with ``__has_feature(cxx_constexpr_string_builtins)``. 2697 2698Memory builtins 2699--------------- 2700 2701Clang provides constant expression evaluation support for builtin forms of the 2702following functions from the C standard library headers 2703``<string.h>`` and ``<wchar.h>``: 2704 2705* ``memcpy`` 2706* ``memmove`` 2707* ``wmemcpy`` 2708* ``wmemmove`` 2709 2710In each case, the builtin form has the name of the C library function prefixed 2711by ``__builtin_``. 2712 2713Constant evaluation support is only provided when the source and destination 2714are pointers to arrays with the same trivially copyable element type, and the 2715given size is an exact multiple of the element size that is no greater than 2716the number of elements accessible through the source and destination operands. 2717 2718Guaranteed inlined copy 2719^^^^^^^^^^^^^^^^^^^^^^^ 2720 2721.. code-block:: c 2722 2723 void __builtin_memcpy_inline(void *dst, const void *src, size_t size); 2724 2725 2726``__builtin_memcpy_inline`` has been designed as a building block for efficient 2727``memcpy`` implementations. It is identical to ``__builtin_memcpy`` but also 2728guarantees not to call any external functions. See LLVM IR `llvm.memcpy.inline 2729<https://llvm.org/docs/LangRef.html#llvm-memcpy-inline-intrinsic>`_ intrinsic 2730for more information. 2731 2732This is useful to implement a custom version of ``memcpy``, implement a 2733``libc`` memcpy or work around the absence of a ``libc``. 2734 2735Note that the `size` argument must be a compile time constant. 2736 2737Note that this intrinsic cannot yet be called in a ``constexpr`` context. 2738 2739 2740Atomic Min/Max builtins with memory ordering 2741-------------------------------------------- 2742 2743There are two atomic builtins with min/max in-memory comparison and swap. 2744The syntax and semantics are similar to GCC-compatible __atomic_* builtins. 2745 2746* ``__atomic_fetch_min`` 2747* ``__atomic_fetch_max`` 2748 2749The builtins work with signed and unsigned integers and require to specify memory ordering. 2750The return value is the original value that was stored in memory before comparison. 2751 2752Example: 2753 2754.. code-block:: c 2755 2756 unsigned int val = __atomic_fetch_min(unsigned int *pi, unsigned int ui, __ATOMIC_RELAXED); 2757 2758The third argument is one of the memory ordering specifiers ``__ATOMIC_RELAXED``, 2759``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``, ``__ATOMIC_RELEASE``, 2760``__ATOMIC_ACQ_REL``, or ``__ATOMIC_SEQ_CST`` following C++11 memory model semantics. 2761 2762In terms or aquire-release ordering barriers these two operations are always 2763considered as operations with *load-store* semantics, even when the original value 2764is not actually modified after comparison. 2765 2766.. _langext-__c11_atomic: 2767 2768__c11_atomic builtins 2769--------------------- 2770 2771Clang provides a set of builtins which are intended to be used to implement 2772C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the 2773``_explicit`` form of the corresponding C11 operation, and are named with a 2774``__c11_`` prefix. The supported operations, and the differences from 2775the corresponding C11 operations, are: 2776 2777* ``__c11_atomic_init`` 2778* ``__c11_atomic_thread_fence`` 2779* ``__c11_atomic_signal_fence`` 2780* ``__c11_atomic_is_lock_free`` (The argument is the size of the 2781 ``_Atomic(...)`` object, instead of its address) 2782* ``__c11_atomic_store`` 2783* ``__c11_atomic_load`` 2784* ``__c11_atomic_exchange`` 2785* ``__c11_atomic_compare_exchange_strong`` 2786* ``__c11_atomic_compare_exchange_weak`` 2787* ``__c11_atomic_fetch_add`` 2788* ``__c11_atomic_fetch_sub`` 2789* ``__c11_atomic_fetch_and`` 2790* ``__c11_atomic_fetch_or`` 2791* ``__c11_atomic_fetch_xor`` 2792* ``__c11_atomic_fetch_max`` 2793* ``__c11_atomic_fetch_min`` 2794 2795The macros ``__ATOMIC_RELAXED``, ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``, 2796``__ATOMIC_RELEASE``, ``__ATOMIC_ACQ_REL``, and ``__ATOMIC_SEQ_CST`` are 2797provided, with values corresponding to the enumerators of C11's 2798``memory_order`` enumeration. 2799 2800(Note that Clang additionally provides GCC-compatible ``__atomic_*`` 2801builtins and OpenCL 2.0 ``__opencl_atomic_*`` builtins. The OpenCL 2.0 2802atomic builtins are an explicit form of the corresponding OpenCL 2.0 2803builtin function, and are named with a ``__opencl_`` prefix. The macros 2804``__OPENCL_MEMORY_SCOPE_WORK_ITEM``, ``__OPENCL_MEMORY_SCOPE_WORK_GROUP``, 2805``__OPENCL_MEMORY_SCOPE_DEVICE``, ``__OPENCL_MEMORY_SCOPE_ALL_SVM_DEVICES``, 2806and ``__OPENCL_MEMORY_SCOPE_SUB_GROUP`` are provided, with values 2807corresponding to the enumerators of OpenCL's ``memory_scope`` enumeration.) 2808 2809Low-level ARM exclusive memory builtins 2810--------------------------------------- 2811 2812Clang provides overloaded builtins giving direct access to the three key ARM 2813instructions for implementing atomic operations. 2814 2815.. code-block:: c 2816 2817 T __builtin_arm_ldrex(const volatile T *addr); 2818 T __builtin_arm_ldaex(const volatile T *addr); 2819 int __builtin_arm_strex(T val, volatile T *addr); 2820 int __builtin_arm_stlex(T val, volatile T *addr); 2821 void __builtin_arm_clrex(void); 2822 2823The types ``T`` currently supported are: 2824 2825* Integer types with width at most 64 bits (or 128 bits on AArch64). 2826* Floating-point types 2827* Pointer types. 2828 2829Note that the compiler does not guarantee it will not insert stores which clear 2830the exclusive monitor in between an ``ldrex`` type operation and its paired 2831``strex``. In practice this is only usually a risk when the extra store is on 2832the same cache line as the variable being modified and Clang will only insert 2833stack stores on its own, so it is best not to use these operations on variables 2834with automatic storage duration. 2835 2836Also, loads and stores may be implicit in code written between the ``ldrex`` and 2837``strex``. Clang will not necessarily mitigate the effects of these either, so 2838care should be exercised. 2839 2840For these reasons the higher level atomic primitives should be preferred where 2841possible. 2842 2843Non-temporal load/store builtins 2844-------------------------------- 2845 2846Clang provides overloaded builtins allowing generation of non-temporal memory 2847accesses. 2848 2849.. code-block:: c 2850 2851 T __builtin_nontemporal_load(T *addr); 2852 void __builtin_nontemporal_store(T value, T *addr); 2853 2854The types ``T`` currently supported are: 2855 2856* Integer types. 2857* Floating-point types. 2858* Vector types. 2859 2860Note that the compiler does not guarantee that non-temporal loads or stores 2861will be used. 2862 2863C++ Coroutines support builtins 2864-------------------------------- 2865 2866.. warning:: 2867 This is a work in progress. Compatibility across Clang/LLVM releases is not 2868 guaranteed. 2869 2870Clang provides experimental builtins to support C++ Coroutines as defined by 2871https://wg21.link/P0057. The following four are intended to be used by the 2872standard library to implement `std::experimental::coroutine_handle` type. 2873 2874**Syntax**: 2875 2876.. code-block:: c 2877 2878 void __builtin_coro_resume(void *addr); 2879 void __builtin_coro_destroy(void *addr); 2880 bool __builtin_coro_done(void *addr); 2881 void *__builtin_coro_promise(void *addr, int alignment, bool from_promise) 2882 2883**Example of use**: 2884 2885.. code-block:: c++ 2886 2887 template <> struct coroutine_handle<void> { 2888 void resume() const { __builtin_coro_resume(ptr); } 2889 void destroy() const { __builtin_coro_destroy(ptr); } 2890 bool done() const { return __builtin_coro_done(ptr); } 2891 // ... 2892 protected: 2893 void *ptr; 2894 }; 2895 2896 template <typename Promise> struct coroutine_handle : coroutine_handle<> { 2897 // ... 2898 Promise &promise() const { 2899 return *reinterpret_cast<Promise *>( 2900 __builtin_coro_promise(ptr, alignof(Promise), /*from-promise=*/false)); 2901 } 2902 static coroutine_handle from_promise(Promise &promise) { 2903 coroutine_handle p; 2904 p.ptr = __builtin_coro_promise(&promise, alignof(Promise), 2905 /*from-promise=*/true); 2906 return p; 2907 } 2908 }; 2909 2910 2911Other coroutine builtins are either for internal clang use or for use during 2912development of the coroutine feature. See `Coroutines in LLVM 2913<https://llvm.org/docs/Coroutines.html#intrinsics>`_ for 2914more information on their semantics. Note that builtins matching the intrinsics 2915that take token as the first parameter (llvm.coro.begin, llvm.coro.alloc, 2916llvm.coro.free and llvm.coro.suspend) omit the token parameter and fill it to 2917an appropriate value during the emission. 2918 2919**Syntax**: 2920 2921.. code-block:: c 2922 2923 size_t __builtin_coro_size() 2924 void *__builtin_coro_frame() 2925 void *__builtin_coro_free(void *coro_frame) 2926 2927 void *__builtin_coro_id(int align, void *promise, void *fnaddr, void *parts) 2928 bool __builtin_coro_alloc() 2929 void *__builtin_coro_begin(void *memory) 2930 void __builtin_coro_end(void *coro_frame, bool unwind) 2931 char __builtin_coro_suspend(bool final) 2932 bool __builtin_coro_param(void *original, void *copy) 2933 2934Note that there is no builtin matching the `llvm.coro.save` intrinsic. LLVM 2935automatically will insert one if the first argument to `llvm.coro.suspend` is 2936token `none`. If a user calls `__builin_suspend`, clang will insert `token none` 2937as the first argument to the intrinsic. 2938 2939Source location builtins 2940------------------------ 2941 2942Clang provides experimental builtins to support C++ standard library implementation 2943of ``std::experimental::source_location`` as specified in http://wg21.link/N4600. 2944With the exception of ``__builtin_COLUMN``, these builtins are also implemented by 2945GCC. 2946 2947**Syntax**: 2948 2949.. code-block:: c 2950 2951 const char *__builtin_FILE(); 2952 const char *__builtin_FUNCTION(); 2953 unsigned __builtin_LINE(); 2954 unsigned __builtin_COLUMN(); // Clang only 2955 2956**Example of use**: 2957 2958.. code-block:: c++ 2959 2960 void my_assert(bool pred, int line = __builtin_LINE(), // Captures line of caller 2961 const char* file = __builtin_FILE(), 2962 const char* function = __builtin_FUNCTION()) { 2963 if (pred) return; 2964 printf("%s:%d assertion failed in function %s\n", file, line, function); 2965 std::abort(); 2966 } 2967 2968 struct MyAggregateType { 2969 int x; 2970 int line = __builtin_LINE(); // captures line where aggregate initialization occurs 2971 }; 2972 static_assert(MyAggregateType{42}.line == __LINE__); 2973 2974 struct MyClassType { 2975 int line = __builtin_LINE(); // captures line of the constructor used during initialization 2976 constexpr MyClassType(int) { assert(line == __LINE__); } 2977 }; 2978 2979**Description**: 2980 2981The builtins ``__builtin_LINE``, ``__builtin_FUNCTION``, and ``__builtin_FILE`` return 2982the values, at the "invocation point", for ``__LINE__``, ``__FUNCTION__``, and 2983``__FILE__`` respectively. These builtins are constant expressions. 2984 2985When the builtins appear as part of a default function argument the invocation 2986point is the location of the caller. When the builtins appear as part of a 2987default member initializer, the invocation point is the location of the 2988constructor or aggregate initialization used to create the object. Otherwise 2989the invocation point is the same as the location of the builtin. 2990 2991When the invocation point of ``__builtin_FUNCTION`` is not a function scope the 2992empty string is returned. 2993 2994Alignment builtins 2995------------------ 2996Clang provides builtins to support checking and adjusting alignment of 2997pointers and integers. 2998These builtins can be used to avoid relying on implementation-defined behavior 2999of arithmetic on integers derived from pointers. 3000Additionally, these builtins retain type information and, unlike bitwise 3001arithmetic, they can perform semantic checking on the alignment value. 3002 3003**Syntax**: 3004 3005.. code-block:: c 3006 3007 Type __builtin_align_up(Type value, size_t alignment); 3008 Type __builtin_align_down(Type value, size_t alignment); 3009 bool __builtin_is_aligned(Type value, size_t alignment); 3010 3011 3012**Example of use**: 3013 3014.. code-block:: c++ 3015 3016 char* global_alloc_buffer; 3017 void* my_aligned_allocator(size_t alloc_size, size_t alignment) { 3018 char* result = __builtin_align_up(global_alloc_buffer, alignment); 3019 // result now contains the value of global_alloc_buffer rounded up to the 3020 // next multiple of alignment. 3021 global_alloc_buffer = result + alloc_size; 3022 return result; 3023 } 3024 3025 void* get_start_of_page(void* ptr) { 3026 return __builtin_align_down(ptr, PAGE_SIZE); 3027 } 3028 3029 void example(char* buffer) { 3030 if (__builtin_is_aligned(buffer, 64)) { 3031 do_fast_aligned_copy(buffer); 3032 } else { 3033 do_unaligned_copy(buffer); 3034 } 3035 } 3036 3037 // In addition to pointers, the builtins can also be used on integer types 3038 // and are evaluatable inside constant expressions. 3039 static_assert(__builtin_align_up(123, 64) == 128, ""); 3040 static_assert(__builtin_align_down(123u, 64) == 64u, ""); 3041 static_assert(!__builtin_is_aligned(123, 64), ""); 3042 3043 3044**Description**: 3045 3046The builtins ``__builtin_align_up``, ``__builtin_align_down``, return their 3047first argument aligned up/down to the next multiple of the second argument. 3048If the value is already sufficiently aligned, it is returned unchanged. 3049The builtin ``__builtin_is_aligned`` returns whether the first argument is 3050aligned to a multiple of the second argument. 3051All of these builtins expect the alignment to be expressed as a number of bytes. 3052 3053These builtins can be used for all integer types as well as (non-function) 3054pointer types. For pointer types, these builtins operate in terms of the integer 3055address of the pointer and return a new pointer of the same type (including 3056qualifiers such as ``const``) with an adjusted address. 3057When aligning pointers up or down, the resulting value must be within the same 3058underlying allocation or one past the end (see C17 6.5.6p8, C++ [expr.add]). 3059This means that arbitrary integer values stored in pointer-type variables must 3060not be passed to these builtins. For those use cases, the builtins can still be 3061used, but the operation must be performed on the pointer cast to ``uintptr_t``. 3062 3063If Clang can determine that the alignment is not a power of two at compile time, 3064it will result in a compilation failure. If the alignment argument is not a 3065power of two at run time, the behavior of these builtins is undefined. 3066 3067Non-standard C++11 Attributes 3068============================= 3069 3070Clang's non-standard C++11 attributes live in the ``clang`` attribute 3071namespace. 3072 3073Clang supports GCC's ``gnu`` attribute namespace. All GCC attributes which 3074are accepted with the ``__attribute__((foo))`` syntax are also accepted as 3075``[[gnu::foo]]``. This only extends to attributes which are specified by GCC 3076(see the list of `GCC function attributes 3077<https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_, `GCC variable 3078attributes <https://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html>`_, and 3079`GCC type attributes 3080<https://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html>`_). As with the GCC 3081implementation, these attributes must appertain to the *declarator-id* in a 3082declaration, which means they must go either at the start of the declaration or 3083immediately after the name being declared. 3084 3085For example, this applies the GNU ``unused`` attribute to ``a`` and ``f``, and 3086also applies the GNU ``noreturn`` attribute to ``f``. 3087 3088.. code-block:: c++ 3089 3090 [[gnu::unused]] int a, f [[gnu::noreturn]] (); 3091 3092Target-Specific Extensions 3093========================== 3094 3095Clang supports some language features conditionally on some targets. 3096 3097ARM/AArch64 Language Extensions 3098------------------------------- 3099 3100Memory Barrier Intrinsics 3101^^^^^^^^^^^^^^^^^^^^^^^^^ 3102Clang implements the ``__dmb``, ``__dsb`` and ``__isb`` intrinsics as defined 3103in the `ARM C Language Extensions Release 2.0 3104<http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_. 3105Note that these intrinsics are implemented as motion barriers that block 3106reordering of memory accesses and side effect instructions. Other instructions 3107like simple arithmetic may be reordered around the intrinsic. If you expect to 3108have no reordering at all, use inline assembly instead. 3109 3110X86/X86-64 Language Extensions 3111------------------------------ 3112 3113The X86 backend has these language extensions: 3114 3115Memory references to specified segments 3116^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3117 3118Annotating a pointer with address space #256 causes it to be code generated 3119relative to the X86 GS segment register, address space #257 causes it to be 3120relative to the X86 FS segment, and address space #258 causes it to be 3121relative to the X86 SS segment. Note that this is a very very low-level 3122feature that should only be used if you know what you're doing (for example in 3123an OS kernel). 3124 3125Here is an example: 3126 3127.. code-block:: c++ 3128 3129 #define GS_RELATIVE __attribute__((address_space(256))) 3130 int foo(int GS_RELATIVE *P) { 3131 return *P; 3132 } 3133 3134Which compiles to (on X86-32): 3135 3136.. code-block:: gas 3137 3138 _foo: 3139 movl 4(%esp), %eax 3140 movl %gs:(%eax), %eax 3141 ret 3142 3143You can also use the GCC compatibility macros ``__seg_fs`` and ``__seg_gs`` for 3144the same purpose. The preprocessor symbols ``__SEG_FS`` and ``__SEG_GS`` 3145indicate their support. 3146 3147PowerPC Language Extensions 3148------------------------------ 3149 3150Set the Floating Point Rounding Mode 3151^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3152PowerPC64/PowerPC64le supports the builtin function ``__builtin_setrnd`` to set 3153the floating point rounding mode. This function will use the least significant 3154two bits of integer argument to set the floating point rounding mode. 3155 3156.. code-block:: c++ 3157 3158 double __builtin_setrnd(int mode); 3159 3160The effective values for mode are: 3161 3162 - 0 - round to nearest 3163 - 1 - round to zero 3164 - 2 - round to +infinity 3165 - 3 - round to -infinity 3166 3167Note that the mode argument will modulo 4, so if the integer argument is greater 3168than 3, it will only use the least significant two bits of the mode. 3169Namely, ``__builtin_setrnd(102))`` is equal to ``__builtin_setrnd(2)``. 3170 3171PowerPC cache builtins 3172^^^^^^^^^^^^^^^^^^^^^^ 3173 3174The PowerPC architecture specifies instructions implementing cache operations. 3175Clang provides builtins that give direct programmer access to these cache 3176instructions. 3177 3178Currently the following builtins are implemented in clang: 3179 3180``__builtin_dcbf`` copies the contents of a modified block from the data cache 3181to main memory and flushes the copy from the data cache. 3182 3183**Syntax**: 3184 3185.. code-block:: c 3186 3187 void __dcbf(const void* addr); /* Data Cache Block Flush */ 3188 3189**Example of Use**: 3190 3191.. code-block:: c 3192 3193 int a = 1; 3194 __builtin_dcbf (&a); 3195 3196Extensions for Static Analysis 3197============================== 3198 3199Clang supports additional attributes that are useful for documenting program 3200invariants and rules for static analysis tools, such as the `Clang Static 3201Analyzer <https://clang-analyzer.llvm.org/>`_. These attributes are documented 3202in the analyzer's `list of source-level annotations 3203<https://clang-analyzer.llvm.org/annotations.html>`_. 3204 3205 3206Extensions for Dynamic Analysis 3207=============================== 3208 3209Use ``__has_feature(address_sanitizer)`` to check if the code is being built 3210with :doc:`AddressSanitizer`. 3211 3212Use ``__has_feature(thread_sanitizer)`` to check if the code is being built 3213with :doc:`ThreadSanitizer`. 3214 3215Use ``__has_feature(memory_sanitizer)`` to check if the code is being built 3216with :doc:`MemorySanitizer`. 3217 3218Use ``__has_feature(safe_stack)`` to check if the code is being built 3219with :doc:`SafeStack`. 3220 3221 3222Extensions for selectively disabling optimization 3223================================================= 3224 3225Clang provides a mechanism for selectively disabling optimizations in functions 3226and methods. 3227 3228To disable optimizations in a single function definition, the GNU-style or C++11 3229non-standard attribute ``optnone`` can be used. 3230 3231.. code-block:: c++ 3232 3233 // The following functions will not be optimized. 3234 // GNU-style attribute 3235 __attribute__((optnone)) int foo() { 3236 // ... code 3237 } 3238 // C++11 attribute 3239 [[clang::optnone]] int bar() { 3240 // ... code 3241 } 3242 3243To facilitate disabling optimization for a range of function definitions, a 3244range-based pragma is provided. Its syntax is ``#pragma clang optimize`` 3245followed by ``off`` or ``on``. 3246 3247All function definitions in the region between an ``off`` and the following 3248``on`` will be decorated with the ``optnone`` attribute unless doing so would 3249conflict with explicit attributes already present on the function (e.g. the 3250ones that control inlining). 3251 3252.. code-block:: c++ 3253 3254 #pragma clang optimize off 3255 // This function will be decorated with optnone. 3256 int foo() { 3257 // ... code 3258 } 3259 3260 // optnone conflicts with always_inline, so bar() will not be decorated. 3261 __attribute__((always_inline)) int bar() { 3262 // ... code 3263 } 3264 #pragma clang optimize on 3265 3266If no ``on`` is found to close an ``off`` region, the end of the region is the 3267end of the compilation unit. 3268 3269Note that a stray ``#pragma clang optimize on`` does not selectively enable 3270additional optimizations when compiling at low optimization levels. This feature 3271can only be used to selectively disable optimizations. 3272 3273The pragma has an effect on functions only at the point of their definition; for 3274function templates, this means that the state of the pragma at the point of an 3275instantiation is not necessarily relevant. Consider the following example: 3276 3277.. code-block:: c++ 3278 3279 template<typename T> T twice(T t) { 3280 return 2 * t; 3281 } 3282 3283 #pragma clang optimize off 3284 template<typename T> T thrice(T t) { 3285 return 3 * t; 3286 } 3287 3288 int container(int a, int b) { 3289 return twice(a) + thrice(b); 3290 } 3291 #pragma clang optimize on 3292 3293In this example, the definition of the template function ``twice`` is outside 3294the pragma region, whereas the definition of ``thrice`` is inside the region. 3295The ``container`` function is also in the region and will not be optimized, but 3296it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of 3297these two instantiations, ``twice`` will be optimized (because its definition 3298was outside the region) and ``thrice`` will not be optimized. 3299 3300Extensions for loop hint optimizations 3301====================================== 3302 3303The ``#pragma clang loop`` directive is used to specify hints for optimizing the 3304subsequent for, while, do-while, or c++11 range-based for loop. The directive 3305provides options for vectorization, interleaving, predication, unrolling and 3306distribution. Loop hints can be specified before any loop and will be ignored if 3307the optimization is not safe to apply. 3308 3309There are loop hints that control transformations (e.g. vectorization, loop 3310unrolling) and there are loop hints that set transformation options (e.g. 3311``vectorize_width``, ``unroll_count``). Pragmas setting transformation options 3312imply the transformation is enabled, as if it was enabled via the corresponding 3313transformation pragma (e.g. ``vectorize(enable)``). If the transformation is 3314disabled (e.g. ``vectorize(disable)``), that takes precedence over 3315transformations option pragmas implying that transformation. 3316 3317Vectorization, Interleaving, and Predication 3318-------------------------------------------- 3319 3320A vectorized loop performs multiple iterations of the original loop 3321in parallel using vector instructions. The instruction set of the target 3322processor determines which vector instructions are available and their vector 3323widths. This restricts the types of loops that can be vectorized. The vectorizer 3324automatically determines if the loop is safe and profitable to vectorize. A 3325vector instruction cost model is used to select the vector width. 3326 3327Interleaving multiple loop iterations allows modern processors to further 3328improve instruction-level parallelism (ILP) using advanced hardware features, 3329such as multiple execution units and out-of-order execution. The vectorizer uses 3330a cost model that depends on the register pressure and generated code size to 3331select the interleaving count. 3332 3333Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled 3334by ``interleave(enable)``. This is useful when compiling with ``-Os`` to 3335manually enable vectorization or interleaving. 3336 3337.. code-block:: c++ 3338 3339 #pragma clang loop vectorize(enable) 3340 #pragma clang loop interleave(enable) 3341 for(...) { 3342 ... 3343 } 3344 3345The vector width is specified by 3346``vectorize_width(_value_[, fixed|scalable])``, where _value_ is a positive 3347integer and the type of vectorization can be specified with an optional 3348second parameter. The default for the second parameter is 'fixed' and 3349refers to fixed width vectorization, whereas 'scalable' indicates the 3350compiler should use scalable vectors instead. Another use of vectorize_width 3351is ``vectorize_width(fixed|scalable)`` where the user can hint at the type 3352of vectorization to use without specifying the exact width. In both variants 3353of the pragma the vectorizer may decide to fall back on fixed width 3354vectorization if the target does not support scalable vectors. 3355 3356The interleave count is specified by ``interleave_count(_value_)``, where 3357_value_ is a positive integer. This is useful for specifying the optimal 3358width/count of the set of target architectures supported by your application. 3359 3360.. code-block:: c++ 3361 3362 #pragma clang loop vectorize_width(2) 3363 #pragma clang loop interleave_count(2) 3364 for(...) { 3365 ... 3366 } 3367 3368Specifying a width/count of 1 disables the optimization, and is equivalent to 3369``vectorize(disable)`` or ``interleave(disable)``. 3370 3371Vector predication is enabled by ``vectorize_predicate(enable)``, for example: 3372 3373.. code-block:: c++ 3374 3375 #pragma clang loop vectorize(enable) 3376 #pragma clang loop vectorize_predicate(enable) 3377 for(...) { 3378 ... 3379 } 3380 3381This predicates (masks) all instructions in the loop, which allows the scalar 3382remainder loop (the tail) to be folded into the main vectorized loop. This 3383might be more efficient when vector predication is efficiently supported by the 3384target platform. 3385 3386Loop Unrolling 3387-------------- 3388 3389Unrolling a loop reduces the loop control overhead and exposes more 3390opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling 3391eliminates the loop and replaces it with an enumerated sequence of loop 3392iterations. Full unrolling is only possible if the loop trip count is known at 3393compile time. Partial unrolling replicates the loop body within the loop and 3394reduces the trip count. 3395 3396If ``unroll(enable)`` is specified the unroller will attempt to fully unroll the 3397loop if the trip count is known at compile time. If the fully unrolled code size 3398is greater than an internal limit the loop will be partially unrolled up to this 3399limit. If the trip count is not known at compile time the loop will be partially 3400unrolled with a heuristically chosen unroll factor. 3401 3402.. code-block:: c++ 3403 3404 #pragma clang loop unroll(enable) 3405 for(...) { 3406 ... 3407 } 3408 3409If ``unroll(full)`` is specified the unroller will attempt to fully unroll the 3410loop if the trip count is known at compile time identically to 3411``unroll(enable)``. However, with ``unroll(full)`` the loop will not be unrolled 3412if the loop count is not known at compile time. 3413 3414.. code-block:: c++ 3415 3416 #pragma clang loop unroll(full) 3417 for(...) { 3418 ... 3419 } 3420 3421The unroll count can be specified explicitly with ``unroll_count(_value_)`` where 3422_value_ is a positive integer. If this value is greater than the trip count the 3423loop will be fully unrolled. Otherwise the loop is partially unrolled subject 3424to the same code size limit as with ``unroll(enable)``. 3425 3426.. code-block:: c++ 3427 3428 #pragma clang loop unroll_count(8) 3429 for(...) { 3430 ... 3431 } 3432 3433Unrolling of a loop can be prevented by specifying ``unroll(disable)``. 3434 3435Loop unroll parameters can be controlled by options 3436`-mllvm -unroll-count=n` and `-mllvm -pragma-unroll-threshold=n`. 3437 3438Loop Distribution 3439----------------- 3440 3441Loop Distribution allows splitting a loop into multiple loops. This is 3442beneficial for example when the entire loop cannot be vectorized but some of the 3443resulting loops can. 3444 3445If ``distribute(enable))`` is specified and the loop has memory dependencies 3446that inhibit vectorization, the compiler will attempt to isolate the offending 3447operations into a new loop. This optimization is not enabled by default, only 3448loops marked with the pragma are considered. 3449 3450.. code-block:: c++ 3451 3452 #pragma clang loop distribute(enable) 3453 for (i = 0; i < N; ++i) { 3454 S1: A[i + 1] = A[i] + B[i]; 3455 S2: C[i] = D[i] * E[i]; 3456 } 3457 3458This loop will be split into two loops between statements S1 and S2. The 3459second loop containing S2 will be vectorized. 3460 3461Loop Distribution is currently not enabled by default in the optimizer because 3462it can hurt performance in some cases. For example, instruction-level 3463parallelism could be reduced by sequentializing the execution of the 3464statements S1 and S2 above. 3465 3466If Loop Distribution is turned on globally with 3467``-mllvm -enable-loop-distribution``, specifying ``distribute(disable)`` can 3468be used the disable it on a per-loop basis. 3469 3470Additional Information 3471---------------------- 3472 3473For convenience multiple loop hints can be specified on a single line. 3474 3475.. code-block:: c++ 3476 3477 #pragma clang loop vectorize_width(4) interleave_count(8) 3478 for(...) { 3479 ... 3480 } 3481 3482If an optimization cannot be applied any hints that apply to it will be ignored. 3483For example, the hint ``vectorize_width(4)`` is ignored if the loop is not 3484proven safe to vectorize. To identify and diagnose optimization issues use 3485`-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the 3486user guide for details. 3487 3488Extensions to specify floating-point flags 3489==================================================== 3490 3491The ``#pragma clang fp`` pragma allows floating-point options to be specified 3492for a section of the source code. This pragma can only appear at file scope or 3493at the start of a compound statement (excluding comments). When using within a 3494compound statement, the pragma is active within the scope of the compound 3495statement. 3496 3497Currently, the following settings can be controlled with this pragma: 3498 3499``#pragma clang fp reassociate`` allows control over the reassociation 3500of floating point expressions. When enabled, this pragma allows the expression 3501``x + (y + z)`` to be reassociated as ``(x + y) + z``. 3502Reassociation can also occur across multiple statements. 3503This pragma can be used to disable reassociation when it is otherwise 3504enabled for the translation unit with the ``-fassociative-math`` flag. 3505The pragma can take two values: ``on`` and ``off``. 3506 3507.. code-block:: c++ 3508 3509 float f(float x, float y, float z) 3510 { 3511 // Enable floating point reassociation across statements 3512 #pragma clang fp reassociate(on) 3513 float t = x + y; 3514 float v = t + z; 3515 } 3516 3517 3518``#pragma clang fp contract`` specifies whether the compiler should 3519contract a multiply and an addition (or subtraction) into a fused FMA 3520operation when supported by the target. 3521 3522The pragma can take three values: ``on``, ``fast`` and ``off``. The ``on`` 3523option is identical to using ``#pragma STDC FP_CONTRACT(ON)`` and it allows 3524fusion as specified the language standard. The ``fast`` option allows fusion 3525in cases when the language standard does not make this possible (e.g. across 3526statements in C). 3527 3528.. code-block:: c++ 3529 3530 for(...) { 3531 #pragma clang fp contract(fast) 3532 a = b[i] * c[i]; 3533 d[i] += a; 3534 } 3535 3536 3537The pragma can also be used with ``off`` which turns FP contraction off for a 3538section of the code. This can be useful when fast contraction is otherwise 3539enabled for the translation unit with the ``-ffp-contract=fast-honor-pragmas`` flag. 3540Note that ``-ffp-contract=fast`` will override pragmas to fuse multiply and 3541addition across statements regardless of any controlling pragmas. 3542 3543``#pragma clang fp exceptions`` specifies floating point exception behavior. It 3544may take one the the values: ``ignore``, ``maytrap`` or ``strict``. Meaning of 3545these values is same as for `constrained floating point intrinsics <http://llvm.org/docs/LangRef.html#constrained-floating-point-intrinsics>`_. 3546 3547.. code-block:: c++ 3548 3549 { 3550 // Preserve floating point exceptions 3551 #pragma clang fp exceptions(strict) 3552 z = x + y; 3553 if (fetestexcept(FE_OVERFLOW)) 3554 ... 3555 } 3556 3557A ``#pragma clang fp`` pragma may contain any number of options: 3558 3559.. code-block:: c++ 3560 3561 void func(float *dest, float a, float b) { 3562 #pragma clang fp exceptions(maytrap) contract(fast) reassociate(on) 3563 ... 3564 } 3565 3566 3567The ``#pragma float_control`` pragma allows precise floating-point 3568semantics and floating-point exception behavior to be specified 3569for a section of the source code. This pragma can only appear at file or 3570namespace scope, within a language linkage specification or at the start of a 3571compound statement (excluding comments). When used within a compound statement, 3572the pragma is active within the scope of the compound statement. This pragma 3573is modeled after a Microsoft pragma with the same spelling and syntax. For 3574pragmas specified at file or namespace scope, or within a language linkage 3575specification, a stack is supported so that the ``pragma float_control`` 3576settings can be pushed or popped. 3577 3578When ``pragma float_control(precise, on)`` is enabled, the section of code 3579governed by the pragma uses precise floating point semantics, effectively 3580``-ffast-math`` is disabled and ``-ffp-contract=on`` 3581(fused multiply add) is enabled. 3582 3583When ``pragma float_control(except, on)`` is enabled, the section of code governed 3584by the pragma behaves as though the command-line option 3585``-ffp-exception-behavior=strict`` is enabled, 3586when ``pragma float_control(precise, off)`` is enabled, the section of code 3587governed by the pragma behaves as though the command-line option 3588``-ffp-exception-behavior=ignore`` is enabled. 3589 3590The full syntax this pragma supports is 3591``float_control(except|precise, on|off [, push])`` and 3592``float_control(push|pop)``. 3593The ``push`` and ``pop`` forms, including using ``push`` as the optional 3594third argument, can only occur at file scope. 3595 3596.. code-block:: c++ 3597 3598 for(...) { 3599 // This block will be compiled with -fno-fast-math and -ffp-contract=on 3600 #pragma float_control(precise, on) 3601 a = b[i] * c[i] + e; 3602 } 3603 3604Specifying an attribute for multiple declarations (#pragma clang attribute) 3605=========================================================================== 3606 3607The ``#pragma clang attribute`` directive can be used to apply an attribute to 3608multiple declarations. The ``#pragma clang attribute push`` variation of the 3609directive pushes a new "scope" of ``#pragma clang attribute`` that attributes 3610can be added to. The ``#pragma clang attribute (...)`` variation adds an 3611attribute to that scope, and the ``#pragma clang attribute pop`` variation pops 3612the scope. You can also use ``#pragma clang attribute push (...)``, which is a 3613shorthand for when you want to add one attribute to a new scope. Multiple push 3614directives can be nested inside each other. 3615 3616The attributes that are used in the ``#pragma clang attribute`` directives 3617can be written using the GNU-style syntax: 3618 3619.. code-block:: c++ 3620 3621 #pragma clang attribute push (__attribute__((annotate("custom"))), apply_to = function) 3622 3623 void function(); // The function now has the annotate("custom") attribute 3624 3625 #pragma clang attribute pop 3626 3627The attributes can also be written using the C++11 style syntax: 3628 3629.. code-block:: c++ 3630 3631 #pragma clang attribute push ([[noreturn]], apply_to = function) 3632 3633 void function(); // The function now has the [[noreturn]] attribute 3634 3635 #pragma clang attribute pop 3636 3637The ``__declspec`` style syntax is also supported: 3638 3639.. code-block:: c++ 3640 3641 #pragma clang attribute push (__declspec(dllexport), apply_to = function) 3642 3643 void function(); // The function now has the __declspec(dllexport) attribute 3644 3645 #pragma clang attribute pop 3646 3647A single push directive accepts only one attribute regardless of the syntax 3648used. 3649 3650Because multiple push directives can be nested, if you're writing a macro that 3651expands to ``_Pragma("clang attribute")`` it's good hygiene (though not 3652required) to add a namespace to your push/pop directives. A pop directive with a 3653namespace will pop the innermost push that has that same namespace. This will 3654ensure that another macro's ``pop`` won't inadvertently pop your attribute. Note 3655that an ``pop`` without a namespace will pop the innermost ``push`` without a 3656namespace. ``push``es with a namespace can only be popped by ``pop`` with the 3657same namespace. For instance: 3658 3659.. code-block:: c++ 3660 3661 #define ASSUME_NORETURN_BEGIN _Pragma("clang attribute AssumeNoreturn.push ([[noreturn]], apply_to = function)") 3662 #define ASSUME_NORETURN_END _Pragma("clang attribute AssumeNoreturn.pop") 3663 3664 #define ASSUME_UNAVAILABLE_BEGIN _Pragma("clang attribute Unavailable.push (__attribute__((unavailable)), apply_to=function)") 3665 #define ASSUME_UNAVAILABLE_END _Pragma("clang attribute Unavailable.pop") 3666 3667 3668 ASSUME_NORETURN_BEGIN 3669 ASSUME_UNAVAILABLE_BEGIN 3670 void function(); // function has [[noreturn]] and __attribute__((unavailable)) 3671 ASSUME_NORETURN_END 3672 void other_function(); // function has __attribute__((unavailable)) 3673 ASSUME_UNAVAILABLE_END 3674 3675Without the namespaces on the macros, ``other_function`` will be annotated with 3676``[[noreturn]]`` instead of ``__attribute__((unavailable))``. This may seem like 3677a contrived example, but its very possible for this kind of situation to appear 3678in real code if the pragmas are spread out across a large file. You can test if 3679your version of clang supports namespaces on ``#pragma clang attribute`` with 3680``__has_extension(pragma_clang_attribute_namespaces)``. 3681 3682Subject Match Rules 3683------------------- 3684 3685The set of declarations that receive a single attribute from the attribute stack 3686depends on the subject match rules that were specified in the pragma. Subject 3687match rules are specified after the attribute. The compiler expects an 3688identifier that corresponds to the subject set specifier. The ``apply_to`` 3689specifier is currently the only supported subject set specifier. It allows you 3690to specify match rules that form a subset of the attribute's allowed subject 3691set, i.e. the compiler doesn't require all of the attribute's subjects. For 3692example, an attribute like ``[[nodiscard]]`` whose subject set includes 3693``enum``, ``record`` and ``hasType(functionType)``, requires the presence of at 3694least one of these rules after ``apply_to``: 3695 3696.. code-block:: c++ 3697 3698 #pragma clang attribute push([[nodiscard]], apply_to = enum) 3699 3700 enum Enum1 { A1, B1 }; // The enum will receive [[nodiscard]] 3701 3702 struct Record1 { }; // The struct will *not* receive [[nodiscard]] 3703 3704 #pragma clang attribute pop 3705 3706 #pragma clang attribute push([[nodiscard]], apply_to = any(record, enum)) 3707 3708 enum Enum2 { A2, B2 }; // The enum will receive [[nodiscard]] 3709 3710 struct Record2 { }; // The struct *will* receive [[nodiscard]] 3711 3712 #pragma clang attribute pop 3713 3714 // This is an error, since [[nodiscard]] can't be applied to namespaces: 3715 #pragma clang attribute push([[nodiscard]], apply_to = any(record, namespace)) 3716 3717 #pragma clang attribute pop 3718 3719Multiple match rules can be specified using the ``any`` match rule, as shown 3720in the example above. The ``any`` rule applies attributes to all declarations 3721that are matched by at least one of the rules in the ``any``. It doesn't nest 3722and can't be used inside the other match rules. Redundant match rules or rules 3723that conflict with one another should not be used inside of ``any``. 3724 3725Clang supports the following match rules: 3726 3727- ``function``: Can be used to apply attributes to functions. This includes C++ 3728 member functions, static functions, operators, and constructors/destructors. 3729 3730- ``function(is_member)``: Can be used to apply attributes to C++ member 3731 functions. This includes members like static functions, operators, and 3732 constructors/destructors. 3733 3734- ``hasType(functionType)``: Can be used to apply attributes to functions, C++ 3735 member functions, and variables/fields whose type is a function pointer. It 3736 does not apply attributes to Objective-C methods or blocks. 3737 3738- ``type_alias``: Can be used to apply attributes to ``typedef`` declarations 3739 and C++11 type aliases. 3740 3741- ``record``: Can be used to apply attributes to ``struct``, ``class``, and 3742 ``union`` declarations. 3743 3744- ``record(unless(is_union))``: Can be used to apply attributes only to 3745 ``struct`` and ``class`` declarations. 3746 3747- ``enum``: Can be be used to apply attributes to enumeration declarations. 3748 3749- ``enum_constant``: Can be used to apply attributes to enumerators. 3750 3751- ``variable``: Can be used to apply attributes to variables, including 3752 local variables, parameters, global variables, and static member variables. 3753 It does not apply attributes to instance member variables or Objective-C 3754 ivars. 3755 3756- ``variable(is_thread_local)``: Can be used to apply attributes to thread-local 3757 variables only. 3758 3759- ``variable(is_global)``: Can be used to apply attributes to global variables 3760 only. 3761 3762- ``variable(is_local)``: Can be used to apply attributes to local variables 3763 only. 3764 3765- ``variable(is_parameter)``: Can be used to apply attributes to parameters 3766 only. 3767 3768- ``variable(unless(is_parameter))``: Can be used to apply attributes to all 3769 the variables that are not parameters. 3770 3771- ``field``: Can be used to apply attributes to non-static member variables 3772 in a record. This includes Objective-C ivars. 3773 3774- ``namespace``: Can be used to apply attributes to ``namespace`` declarations. 3775 3776- ``objc_interface``: Can be used to apply attributes to ``@interface`` 3777 declarations. 3778 3779- ``objc_protocol``: Can be used to apply attributes to ``@protocol`` 3780 declarations. 3781 3782- ``objc_category``: Can be used to apply attributes to category declarations, 3783 including class extensions. 3784 3785- ``objc_method``: Can be used to apply attributes to Objective-C methods, 3786 including instance and class methods. Implicit methods like implicit property 3787 getters and setters do not receive the attribute. 3788 3789- ``objc_method(is_instance)``: Can be used to apply attributes to Objective-C 3790 instance methods. 3791 3792- ``objc_property``: Can be used to apply attributes to ``@property`` 3793 declarations. 3794 3795- ``block``: Can be used to apply attributes to block declarations. This does 3796 not include variables/fields of block pointer type. 3797 3798The use of ``unless`` in match rules is currently restricted to a strict set of 3799sub-rules that are used by the supported attributes. That means that even though 3800``variable(unless(is_parameter))`` is a valid match rule, 3801``variable(unless(is_thread_local))`` is not. 3802 3803Supported Attributes 3804-------------------- 3805 3806Not all attributes can be used with the ``#pragma clang attribute`` directive. 3807Notably, statement attributes like ``[[fallthrough]]`` or type attributes 3808like ``address_space`` aren't supported by this directive. You can determine 3809whether or not an attribute is supported by the pragma by referring to the 3810:doc:`individual documentation for that attribute <AttributeReference>`. 3811 3812The attributes are applied to all matching declarations individually, even when 3813the attribute is semantically incorrect. The attributes that aren't applied to 3814any declaration are not verified semantically. 3815 3816Specifying section names for global objects (#pragma clang section) 3817=================================================================== 3818 3819The ``#pragma clang section`` directive provides a means to assign section-names 3820to global variables, functions and static variables. 3821 3822The section names can be specified as: 3823 3824.. code-block:: c++ 3825 3826 #pragma clang section bss="myBSS" data="myData" rodata="myRodata" relro="myRelro" text="myText" 3827 3828The section names can be reverted back to default name by supplying an empty 3829string to the section kind, for example: 3830 3831.. code-block:: c++ 3832 3833 #pragma clang section bss="" data="" text="" rodata="" relro="" 3834 3835The ``#pragma clang section`` directive obeys the following rules: 3836 3837* The pragma applies to all global variable, statics and function declarations 3838 from the pragma to the end of the translation unit. 3839 3840* The pragma clang section is enabled automatically, without need of any flags. 3841 3842* This feature is only defined to work sensibly for ELF targets. 3843 3844* If section name is specified through _attribute_((section("myname"))), then 3845 the attribute name gains precedence. 3846 3847* Global variables that are initialized to zero will be placed in the named 3848 bss section, if one is present. 3849 3850* The ``#pragma clang section`` directive does not does try to infer section-kind 3851 from the name. For example, naming a section "``.bss.mySec``" does NOT mean 3852 it will be a bss section name. 3853 3854* The decision about which section-kind applies to each global is taken in the back-end. 3855 Once the section-kind is known, appropriate section name, as specified by the user using 3856 ``#pragma clang section`` directive, is applied to that global. 3857 3858Specifying Linker Options on ELF Targets 3859======================================== 3860 3861The ``#pragma comment(lib, ...)`` directive is supported on all ELF targets. 3862The second parameter is the library name (without the traditional Unix prefix of 3863``lib``). This allows you to provide an implicit link of dependent libraries. 3864 3865Evaluating Object Size Dynamically 3866================================== 3867 3868Clang supports the builtin ``__builtin_dynamic_object_size``, the semantics are 3869the same as GCC's ``__builtin_object_size`` (which Clang also supports), but 3870``__builtin_dynamic_object_size`` can evaluate the object's size at runtime. 3871``__builtin_dynamic_object_size`` is meant to be used as a drop-in replacement 3872for ``__builtin_object_size`` in libraries that support it. 3873 3874For instance, here is a program that ``__builtin_dynamic_object_size`` will make 3875safer: 3876 3877.. code-block:: c 3878 3879 void copy_into_buffer(size_t size) { 3880 char* buffer = malloc(size); 3881 strlcpy(buffer, "some string", strlen("some string")); 3882 // Previous line preprocesses to: 3883 // __builtin___strlcpy_chk(buffer, "some string", strlen("some string"), __builtin_object_size(buffer, 0)) 3884 } 3885 3886Since the size of ``buffer`` can't be known at compile time, Clang will fold 3887``__builtin_object_size(buffer, 0)`` into ``-1``. However, if this was written 3888as ``__builtin_dynamic_object_size(buffer, 0)``, Clang will fold it into 3889``size``, providing some extra runtime safety. 3890 3891Deprecating Macros 3892================== 3893 3894Clang supports the pragma ``#pragma clang deprecated``, which can be used to 3895provide deprecation warnings for macro uses. For example: 3896 3897.. code-block:: c 3898 3899 #define MIN(x, y) x < y ? x : y 3900 #pragma clang deprecated(MIN, "use std::min instead") 3901 3902 void min(int a, int b) { 3903 return MIN(a, b); // warning: MIN is deprecated: use std::min instead 3904 } 3905 3906``#pragma clang deprecated`` should be preferred for this purpose over 3907``#pragma GCC warning`` because the warning can be controlled with 3908``-Wdeprecated``. 3909 3910Restricted Expansion Macros 3911=========================== 3912 3913Clang supports the pragma ``#pragma clang restrict_expansion``, which can be 3914used restrict macro expansion in headers. This can be valuable when providing 3915headers with ABI stability requirements. Any expansion of the annotated macro 3916processed by the preprocessor after the ``#pragma`` annotation will log a 3917warning. Redefining the macro or undefining the macro will not be diagnosed, nor 3918will expansion of the macro within the main source file. For example: 3919 3920.. code-block:: c 3921 3922 #define TARGET_ARM 1 3923 #pragma clang restrict_expansion(TARGET_ARM, "<reason>") 3924 3925 /// Foo.h 3926 struct Foo { 3927 #if TARGET_ARM // warning: TARGET_ARM is marked unsafe in headers: <reason> 3928 uint32_t X; 3929 #else 3930 uint64_t X; 3931 #endif 3932 }; 3933 3934 /// main.c 3935 #include "foo.h" 3936 #if TARGET_ARM // No warning in main source file 3937 X_TYPE uint32_t 3938 #else 3939 X_TYPE uint64_t 3940 #endif 3941 3942This warning is controlled by ``-Wpedantic-macros``. 3943 3944Final Macros 3945============ 3946 3947Clang supports the pragma ``#pragma clang final``, which can be used to 3948mark macros as final, meaning they cannot be undef'd or re-defined. For example: 3949 3950.. code-block:: c 3951 3952 #define FINAL_MACRO 1 3953 #pragma clang final(FINAL_MACRO) 3954 3955 #define FINAL_MACRO // warning: FINAL_MACRO is marked final and should not be redefined 3956 #undef FINAL_MACRO // warning: FINAL_MACRO is marked final and should not be undefined 3957 3958This is useful for enforcing system-provided macros that should not be altered 3959in user headers or code. This is controlled by ``-Wpedantic-macros``. Final 3960macros will always warn on redefinition, including situations with identical 3961bodies and in system headers. 3962 3963Extended Integer Types 3964====================== 3965 3966Clang supports a set of extended integer types under the syntax ``_ExtInt(N)`` 3967where ``N`` is an integer that specifies the number of bits that are used to represent 3968the type, including the sign bit. The keyword ``_ExtInt`` is a type specifier, thus 3969it can be used in any place a type can, including as a non-type-template-parameter, 3970as the type of a bitfield, and as the underlying type of an enumeration. 3971 3972An extended integer can be declared either signed, or unsigned by using the 3973``signed``/``unsigned`` keywords. If no sign specifier is used or if the ``signed`` 3974keyword is used, the extended integer type is a signed integer and can represent 3975negative values. 3976 3977The ``N`` expression is an integer constant expression, which specifies the number 3978of bits used to represent the type, following normal integer representations for 3979both signed and unsigned types. Both a signed and unsigned extended integer of the 3980same ``N`` value will have the same number of bits in its representation. Many 3981architectures don't have a way of representing non power-of-2 integers, so these 3982architectures emulate these types using larger integers. In these cases, they are 3983expected to follow the 'as-if' rule and do math 'as-if' they were done at the 3984specified number of bits. 3985 3986In order to be consistent with the C language specification, and make the extended 3987integer types useful for their intended purpose, extended integers follow the C 3988standard integer conversion ranks. An extended integer type has a greater rank than 3989any integer type with less precision. However, they have lower rank than any 3990of the built in or other integer types (such as __int128). Usual arithmetic conversions 3991also work the same, where the smaller ranked integer is converted to the larger. 3992 3993The one exception to the C rules for integers for these types is Integer Promotion. 3994Unary +, -, and ~ operators typically will promote operands to ``int``. Doing these 3995promotions would inflate the size of required hardware on some platforms, so extended 3996integer types aren't subject to the integer promotion rules in these cases. 3997 3998In languages (such as OpenCL) that define shift by-out-of-range behavior as a mask, 3999non-power-of-two versions of these types use an unsigned remainder operation to constrain 4000the value to the proper range, preventing undefined behavior. 4001 4002Extended integer types are aligned to the next greatest power-of-2 up to 64 bits. 4003The size of these types for the purposes of layout and ``sizeof`` are the number of 4004bits aligned to this calculated alignment. This permits the use of these types in 4005allocated arrays using common ``sizeof(Array)/sizeof(ElementType)`` pattern. 4006 4007Extended integer types work with the C _Atomic type modifier, however only precisions 4008that are powers-of-2 greater than 8 bit are accepted. 4009 4010Extended integer types align with existing calling conventions. They have the same size 4011and alignment as the smallest basic type that can contain them. Types that are larger 4012than 64 bits are handled in the same way as _int128 is handled; they are conceptually 4013treated as struct of register size chunks. They number of chunks are the smallest 4014number that can contain the types which does not necessarily mean a power-of-2 size. 4015 4016Intrinsics Support within Constant Expressions 4017============================================== 4018 4019The following builtin intrinsics can be used in constant expressions: 4020 4021* ``__builtin_bitreverse8`` 4022* ``__builtin_bitreverse16`` 4023* ``__builtin_bitreverse32`` 4024* ``__builtin_bitreverse64`` 4025* ``__builtin_bswap16`` 4026* ``__builtin_bswap32`` 4027* ``__builtin_bswap64`` 4028* ``__builtin_clrsb`` 4029* ``__builtin_clrsbl`` 4030* ``__builtin_clrsbll`` 4031* ``__builtin_clz`` 4032* ``__builtin_clzl`` 4033* ``__builtin_clzll`` 4034* ``__builtin_clzs`` 4035* ``__builtin_ctz`` 4036* ``__builtin_ctzl`` 4037* ``__builtin_ctzll`` 4038* ``__builtin_ctzs`` 4039* ``__builtin_ffs`` 4040* ``__builtin_ffsl`` 4041* ``__builtin_ffsll`` 4042* ``__builtin_fpclassify`` 4043* ``__builtin_inf`` 4044* ``__builtin_isinf`` 4045* ``__builtin_isinf_sign`` 4046* ``__builtin_isfinite`` 4047* ``__builtin_isnan`` 4048* ``__builtin_isnormal`` 4049* ``__builtin_nan`` 4050* ``__builtin_nans`` 4051* ``__builtin_parity`` 4052* ``__builtin_parityl`` 4053* ``__builtin_parityll`` 4054* ``__builtin_popcount`` 4055* ``__builtin_popcountl`` 4056* ``__builtin_popcountll`` 4057* ``__builtin_rotateleft8`` 4058* ``__builtin_rotateleft16`` 4059* ``__builtin_rotateleft32`` 4060* ``__builtin_rotateleft64`` 4061* ``__builtin_rotateright8`` 4062* ``__builtin_rotateright16`` 4063* ``__builtin_rotateright32`` 4064* ``__builtin_rotateright64`` 4065 4066The following x86-specific intrinsics can be used in constant expressions: 4067 4068* ``_bit_scan_forward`` 4069* ``_bit_scan_reverse`` 4070* ``__bsfd`` 4071* ``__bsfq`` 4072* ``__bsrd`` 4073* ``__bsrq`` 4074* ``__bswap`` 4075* ``__bswapd`` 4076* ``__bswap64`` 4077* ``__bswapq`` 4078* ``_castf32_u32`` 4079* ``_castf64_u64`` 4080* ``_castu32_f32`` 4081* ``_castu64_f64`` 4082* ``_mm_popcnt_u32`` 4083* ``_mm_popcnt_u64`` 4084* ``_popcnt32`` 4085* ``_popcnt64`` 4086* ``__popcntd`` 4087* ``__popcntq`` 4088* ``__rolb`` 4089* ``__rolw`` 4090* ``__rold`` 4091* ``__rolq`` 4092* ``__rorb`` 4093* ``__rorw`` 4094* ``__rord`` 4095* ``__rorq`` 4096* ``_rotl`` 4097* ``_rotr`` 4098* ``_rotwl`` 4099* ``_rotwr`` 4100* ``_lrotl`` 4101* ``_lrotr`` 4102