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