1 =========================
2 Clang Language Extensions
3 =========================
15 AutomaticReferenceCounting
21 This document describes the language extensions provided by Clang. In addition
22 to the language extensions listed here, Clang aims to support a broad range of
23 GCC extensions. Please see the `GCC manual
24 <https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on
27 .. _langext-feature_check:
29 Feature Checking Macros
30 =======================
32 Language extensions can be very useful, but only if you know you can depend on
33 them. In order to allow fine-grain features checks, we support three builtin
34 function-like macros. This allows you to directly test for a feature in your
35 code without having to resort to something like autoconf or fragile "compiler
41 This function-like macro takes a single identifier argument that is the name of
42 a builtin function, a builtin pseudo-function (taking one or more type
43 arguments), or a builtin template.
44 It evaluates to 1 if the builtin is supported or 0 if not.
45 It can be used like this:
49 #ifndef __has_builtin // Optional of course.
50 #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
54 #if __has_builtin(__builtin_trap)
63 Prior to Clang 10, ``__has_builtin`` could not be used to detect most builtin
66 ``__has_builtin`` should not be used to detect support for a builtin macro;
67 use ``#ifdef`` instead.
69 .. _langext-__has_feature-__has_extension:
71 ``__has_feature`` and ``__has_extension``
72 -----------------------------------------
74 These function-like macros take a single identifier argument that is the name
75 of a feature. ``__has_feature`` evaluates to 1 if the feature is both
76 supported by Clang and standardized in the current language standard or 0 if
77 not (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
79 current language (either as a language extension or a standard language
80 feature) or 0 if not. They can be used like this:
84 #ifndef __has_feature // Optional of course.
85 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
87 #ifndef __has_extension
88 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
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.
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.
103 .. _langext-has-feature-back-compat:
105 For backward compatibility, ``__has_feature`` can also be used to test
106 for support for non-standardized features, i.e. features not prefixed ``c_``,
107 ``cxx_`` or ``objc_``.
109 Another use of ``__has_feature`` is to check for compiler features not related
110 to the language standard, such as e.g. :doc:`AddressSanitizer
113 If the ``-pedantic-errors`` option is given, ``__has_extension`` is equivalent
114 to ``__has_feature``.
116 The feature tag is described along with the language feature below.
118 The feature name or extension name can also be specified with a preceding and
119 following ``__`` (double underscore) to avoid interference from a macro with
120 the same name. For instance, ``__cxx_rvalue_references__`` can be used instead
121 of ``cxx_rvalue_references``.
123 ``__has_cpp_attribute``
124 -----------------------
126 This function-like macro is available in C++20 by default, and is provided as an
127 extension in earlier language standards. It takes a single argument that is the
128 name of a double-square-bracket-style attribute. The argument can either be a
129 single identifier or a scoped identifier. If the attribute is supported, a
130 nonzero value is returned. If the attribute is a standards-based attribute, this
131 macro returns a nonzero value based on the year and month in which the attribute
132 was voted into the working draft. See `WG21 SD-6
133 <https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations>`_
134 for the list of values returned for standards-based attributes. If the attribute
135 is not supported by the current compilation target, this macro evaluates to 0.
136 It can be used like this:
140 #ifndef __has_cpp_attribute // For backwards compatibility
141 #define __has_cpp_attribute(x) 0
145 #if __has_cpp_attribute(clang::fallthrough)
146 #define FALLTHROUGH [[clang::fallthrough]]
152 The attribute scope tokens ``clang`` and ``_Clang`` are interchangeable, as are
153 the attribute scope tokens ``gnu`` and ``__gnu__``. Attribute tokens in either
154 of these namespaces can be specified with a preceding and following ``__``
155 (double underscore) to avoid interference from a macro with the same name. For
156 instance, ``gnu::__const__`` can be used instead of ``gnu::const``.
158 ``__has_c_attribute``
159 ---------------------
161 This function-like macro takes a single argument that is the name of an
162 attribute exposed with the double square-bracket syntax in C mode. The argument
163 can either be a single identifier or a scoped identifier. If the attribute is
164 supported, a nonzero value is returned. If the attribute is not supported by the
165 current compilation target, this macro evaluates to 0. It can be used like this:
169 #ifndef __has_c_attribute // Optional of course.
170 #define __has_c_attribute(x) 0 // Compatibility with non-clang compilers.
174 #if __has_c_attribute(fallthrough)
175 #define FALLTHROUGH [[fallthrough]]
181 The attribute scope tokens ``clang`` and ``_Clang`` are interchangeable, as are
182 the attribute scope tokens ``gnu`` and ``__gnu__``. Attribute tokens in either
183 of these namespaces can be specified with a preceding and following ``__``
184 (double underscore) to avoid interference from a macro with the same name. For
185 instance, ``gnu::__const__`` can be used instead of ``gnu::const``.
190 This function-like macro takes a single identifier argument that is the name of
191 a GNU-style attribute. It evaluates to 1 if the attribute is supported by the
192 current compilation target, or 0 if not. It can be used like this:
196 #ifndef __has_attribute // Optional of course.
197 #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
201 #if __has_attribute(always_inline)
202 #define ALWAYS_INLINE __attribute__((always_inline))
204 #define ALWAYS_INLINE
208 The 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
210 instance, ``__always_inline__`` can be used instead of ``always_inline``.
213 ``__has_declspec_attribute``
214 ----------------------------
216 This function-like macro takes a single identifier argument that is the name of
217 an attribute implemented as a Microsoft-style ``__declspec`` attribute. It
218 evaluates to 1 if the attribute is supported by the current compilation target,
219 or 0 if not. It can be used like this:
223 #ifndef __has_declspec_attribute // Optional of course.
224 #define __has_declspec_attribute(x) 0 // Compatibility with non-clang compilers.
228 #if __has_declspec_attribute(dllexport)
229 #define DLLEXPORT __declspec(dllexport)
235 The 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
237 instance, ``__dllexport__`` can be used instead of ``dllexport``.
242 This function-like macro takes a single identifier argument that might be either
243 a reserved word or a regular identifier. It evaluates to 1 if the argument is just
244 a regular identifier and not a reserved word, in the sense that it can then be
245 used as the name of a user-defined function or variable. Otherwise it evaluates
246 to 0. It can be used like this:
251 #ifdef __is_identifier // Compatibility with non-clang compilers.
252 #if __is_identifier(__wchar_t)
253 typedef wchar_t __wchar_t;
257 __wchar_t WideCharacter;
260 Include File Checking Macros
261 ============================
263 Not all developments systems have the same include files. The
264 :ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow
265 you to check for the existence of an include file before doing a possibly
266 failing ``#include`` directive. Include file checking macros must be used
267 as expressions in ``#if`` or ``#elif`` preprocessing directives.
269 .. _langext-__has_include:
274 This function-like macro takes a single file name string argument that is the
275 name of an include file. It evaluates to 1 if the file can be found using the
276 include paths, or 0 otherwise:
280 // Note the two possible file name string formats.
281 #if __has_include("myinclude.h") && __has_include(<stdint.h>)
282 # include "myinclude.h"
285 To test for this feature, use ``#if defined(__has_include)``:
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"
296 .. _langext-__has_include_next:
298 ``__has_include_next``
299 ----------------------
301 This function-like macro takes a single file name string argument that is the
302 name of an include file. It is like ``__has_include`` except that it looks for
303 the second instance of the given file found in the include paths. It evaluates
304 to 1 if the second instance of the file can be found using the include paths,
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"
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"
321 Note that ``__has_include_next``, like the GNU extension ``#include_next``
322 directive, is intended for use in headers only, and will issue a warning if
323 used in the top-level compilation file. A warning will also be issued if an
324 absolute path is used in the file argument.
329 This function-like macro takes a string literal that represents a command line
330 option for a warning and returns true if that is a valid warning option.
334 #if __has_warning("-Wformat")
338 .. _languageextensions-builtin-macros:
344 Defined to a string that contains the name of the main input file passed to
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.
353 Defined to an integer value that starts at zero and is incremented each time
354 the ``__COUNTER__`` macro is expanded.
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.
361 Defined to the date and time of the last modification of the current source
365 Defined when compiling with Clang
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`.
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`.
379 ``__clang_patchlevel__``
380 Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).
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)``".
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.)
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.)
400 Vectors and Extended Vectors
401 ============================
403 Supports the GCC, OpenCL, AltiVec and NEON vector extensions.
405 OpenCL vector types are created using the ``ext_vector_type`` attribute. It
406 supports the ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example
411 typedef float float4 __attribute__((ext_vector_type(4)));
412 typedef float float2 __attribute__((ext_vector_type(2)));
414 float4 foo(float2 a, float2 b) {
421 Query for this feature with ``__has_attribute(ext_vector_type)``.
423 Giving ``-maltivec`` option to clang enables support for AltiVec vector syntax
424 and functions. For example:
428 vector float foo(vector int a) {
430 b = vec_add(a, a) + a;
431 return (vector float)b;
434 NEON vector types are created using ``neon_vector_type`` and
435 ``neon_polyvector_type`` attributes. For example:
439 typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t;
440 typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t;
442 int8x8_t foo(int8x8_t a) {
451 Vector literals can be used to create vectors from a set of scalars, or
452 vectors. Either parentheses or braces form can be used. In the parentheses
453 form the number of literal values specified must be one, i.e. referring to a
454 scalar value, or must match the size of the vector type being created. If a
455 single scalar literal value is specified, the scalar literal value will be
456 replicated to all the components of the vector type. In the brackets form any
457 number of literals can be specified. For example:
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)));
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));
477 The table below shows the support for each operation by vector extension. A
478 dash indicates that an operation is not accepted according to a corresponding
481 ============================== ======= ======= ============= =======
482 Operator OpenCL AltiVec GCC NEON
483 ============================== ======= ======= ============= =======
485 unary operators +, -- yes yes yes --
486 ++, -- -- yes yes yes --
487 +,--,*,/,% yes yes yes --
488 bitwise operators &,|,^,~ yes yes yes --
490 !, &&, || yes -- yes --
491 ==, !=, >, <, >=, <= yes yes yes --
493 ?: [#]_ yes -- yes --
494 sizeof yes yes yes yes
495 C-style cast yes yes yes no
496 reinterpret_cast yes no yes no
497 static_cast yes no yes no
498 const_cast no no no no
499 ============================== ======= ======= ============= =======
501 See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`.
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).
512 **Note: The implementation of vector builtins is work-in-progress and incomplete.**
514 In addition to the operators mentioned above, Clang provides a set of builtins
515 to perform additional operations on certain scalar and vector types.
517 Let ``T`` be one of the following types:
519 * an integer type (as in C2x 6.2.5p19), but excluding enumerated types and _Bool
520 * the standard floating types float or double
521 * a half-precision floating point type, if one is supported on the target
524 For scalar types, consider the operation applied to a vector with a single element.
526 *Elementwise Builtins*
528 Each builtin returns a vector equivalent to applying the specified operation
529 elementwise to the input.
531 Unless specified otherwise operation(±0) = ±0 and operation(±infinity) = ±infinity
533 ========================================= ================================================================ =========================================
534 Name Operation Supported element types
535 ========================================= ================================================================ =========================================
536 T __builtin_elementwise_abs(T x) return the absolute value of a number x; the absolute value of signed integer and floating point types
537 the most negative integer remains the most negative integer
538 T __builtin_elementwise_ceil(T x) return the smallest integral value greater than or equal to x floating point types
539 T __builtin_elementwise_floor(T x) return the largest integral value less than or equal to x floating point types
540 T __builtin_elementwise_roundeven(T x) round x to the nearest integer value in floating point format, floating point types
541 rounding halfway cases to even (that is, to the nearest value
542 that is an even integer), regardless of the current rounding
544 T__builtin_elementwise_trunc(T x) return the integral value nearest to but no larger in floating point types
546 T __builtin_elementwise_max(T x, T y) return x or y, whichever is larger integer and floating point types
547 T __builtin_elementwise_min(T x, T y) return x or y, whichever is smaller integer and floating point types
548 ========================================= ================================================================ =========================================
553 Each builtin returns a scalar equivalent to applying the specified
554 operation(x, y) as recursive even-odd pairwise reduction to all vector
555 elements. ``operation(x, y)`` is repeatedly applied to each non-overlapping
556 even-odd element pair with indices ``i * 2`` and ``i * 2 + 1`` with
557 ``i in [0, Number of elements / 2)``. If the numbers of elements is not a
558 power of 2, the vector is widened with neutral elements for the reduction
559 at the end to the next power of 2.
565 __builtin_reduce_add([e3, e2, e1, e0]) = __builtin_reduced_add([e3 + e2, e1 + e0])
566 = (e3 + e2) + (e1 + e0)
569 Let ``VT`` be a vector type and ``ET`` the element type of ``VT``.
571 ======================================= ================================================================ ==================================
572 Name Operation Supported element types
573 ======================================= ================================================================ ==================================
574 ET __builtin_reduce_max(VT a) return x or y, whichever is larger; If exactly one argument is integer and floating point types
575 a NaN, return the other argument. If both arguments are NaNs,
577 ET __builtin_reduce_min(VT a) return x or y, whichever is smaller; If exactly one argument integer and floating point types
578 is a NaN, return the other argument. If both arguments are
579 NaNs, fmax() return a NaN.
580 ET __builtin_reduce_add(VT a) \+ integer and floating point types
581 ET __builtin_reduce_and(VT a) & integer types
582 ET __builtin_reduce_or(VT a) \| integer types
583 ET __builtin_reduce_xor(VT a) ^ integer types
584 ======================================= ================================================================ ==================================
589 Clang provides an extension for matrix types, which is currently being
590 implemented. See :ref:`the draft specification <matrixtypes>` for more details.
592 For example, the code below uses the matrix types extension to multiply two 4x4
593 float matrices and add the result to a third 4x4 matrix.
597 typedef float m4x4_t __attribute__((matrix_type(4, 4)));
599 m4x4_t f(m4x4_t a, m4x4_t b, m4x4_t c) {
603 The matrix type extension also supports operations on a matrix and a scalar.
607 typedef float m4x4_t __attribute__((matrix_type(4, 4)));
610 return (a + 23) * 12;
613 The matrix type extension supports division on a matrix and a scalar but not on a matrix and a matrix.
617 typedef float m4x4_t __attribute__((matrix_type(4, 4)));
624 The matrix type extension supports compound assignments for addition, subtraction, and multiplication on matrices
625 and on a matrix and a scalar, provided their types are consistent.
629 typedef float m4x4_t __attribute__((matrix_type(4, 4)));
631 m4x4_t f(m4x4_t a, m4x4_t b) {
640 The matrix type extension supports explicit casts. Implicit type conversion between matrix types is not allowed.
644 typedef int ix5x5 __attribute__((matrix_type(5, 5)));
645 typedef float fx5x5 __attribute__((matrix_type(5, 5)));
647 fx5x5 f1(ix5x5 i, fx5x5 f) {
652 template <typename X>
653 using matrix_4_4 = X __attribute__((matrix_type(4, 4)));
656 matrix_5_5<double> d;
658 i = (matrix_5_5<int>)d;
659 i = static_cast<matrix_5_5<int>>(d);
662 Half-Precision Floating Point
663 =============================
665 Clang supports three half-precision (16-bit) floating point types: ``__fp16``,
666 ``_Float16`` and ``__bf16``. These types are supported in all language modes.
668 ``__fp16`` is supported on every target, as it is purely a storage format; see below.
669 ``_Float16`` is currently only supported on the following targets, with further
670 targets pending ABI standardization:
673 * 64-bit ARM (AArch64)
676 * X86 (Only available under feature AVX512-FP16)
678 ``_Float16`` will be supported on more targets as they define ABIs for it.
680 ``__bf16`` is purely a storage format; it is currently only supported on the following targets:
682 * 64-bit ARM (AArch64)
684 The ``__bf16`` type is only available when supported in hardware.
686 ``__fp16`` is a storage and interchange format only. This means that values of
687 ``__fp16`` are immediately promoted to (at least) ``float`` when used in arithmetic
688 operations, so that e.g. the result of adding two ``__fp16`` values has type ``float``.
689 The 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>`_).
690 Clang uses the ``binary16`` format from IEEE 754-2008 for ``__fp16``, not the ARM
693 ``_Float16`` is an interchange floating-point type. This means that, just like arithmetic on
694 ``float`` or ``double``, arithmetic on ``_Float16`` operands is formally performed in the
695 ``_Float16`` type, so that e.g. the result of adding two ``_Float16`` values has type
696 ``_Float16``. The behavior of ``_Float16`` is specified by ISO/IEC TS 18661-3:2015
697 ("Floating-point extensions for C"). As with ``__fp16``, Clang uses the ``binary16``
698 format from IEEE 754-2008 for ``_Float16``.
700 ``_Float16`` arithmetic will be performed using native half-precision support
701 when available on the target (e.g. on ARMv8.2a); otherwise it will be performed
702 at a higher precision (currently always ``float``) and then truncated down to
703 ``_Float16``. Note that C and C++ allow intermediate floating-point operands
704 of an expression to be computed with greater precision than is expressible in
705 their type, so Clang may avoid intermediate truncations in certain cases; this may
706 lead to results that are inconsistent with native arithmetic.
708 It is recommended that portable code use ``_Float16`` instead of ``__fp16``,
709 as it has been defined by the C standards committee and has behavior that is
710 more familiar to most programmers.
712 Because ``__fp16`` operands are always immediately promoted to ``float``, the
713 common real type of ``__fp16`` and ``_Float16`` for the purposes of the usual
714 arithmetic conversions is ``float``.
716 A literal can be given ``_Float16`` type using the suffix ``f16``. For example,
719 Because default argument promotion only applies to the standard floating-point
720 types, ``_Float16`` values are not promoted to ``double`` when passed as variadic
721 or untyped arguments. As a consequence, some caution must be taken when using
722 certain library facilities with ``_Float16``; for example, there is no ``printf`` format
723 specifier for ``_Float16``, and (unlike ``float``) it will not be implicitly promoted to
724 ``double`` when passed to ``printf``, so the programmer must explicitly cast it to
725 ``double`` before using it with an ``%f`` or similar specifier.
727 Messages on ``deprecated`` and ``unavailable`` Attributes
728 =========================================================
730 An optional string message can be added to the ``deprecated`` and
731 ``unavailable`` attributes. For example:
735 void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));
737 If the deprecated or unavailable declaration is used, the message will be
738 incorporated into the appropriate diagnostic:
742 harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
743 [-Wdeprecated-declarations]
747 Query for this feature with
748 ``__has_extension(attribute_deprecated_with_message)`` and
749 ``__has_extension(attribute_unavailable_with_message)``.
751 Attributes on Enumerators
752 =========================
754 Clang allows attributes to be written on individual enumerators. This allows
755 enumerators to be deprecated, made unavailable, etc. The attribute must appear
756 after the enumerator name and before any initializer, like so:
763 OM_Terrified __attribute__((deprecated)),
764 OM_AbortOnError __attribute__((deprecated)) = 4
767 Attributes on the ``enum`` declaration do not apply to individual enumerators.
769 Query for this feature with ``__has_extension(enumerator_attributes)``.
771 C++11 Attributes on using-declarations
772 ======================================
774 Clang allows C++-style ``[[]]`` attributes to be written on using-declarations.
779 [[clang::using_if_exists]] using foo::bar;
780 using foo::baz [[clang::using_if_exists]];
782 You can test for support for this extension with
783 ``__has_extension(cxx_attributes_on_using_declarations)``.
785 'User-Specified' System Frameworks
786 ==================================
788 Clang provides a mechanism by which frameworks can be built in such a way that
789 they will always be treated as being "system frameworks", even if they are not
790 present in a system framework directory. This can be useful to system
791 framework developers who want to be able to test building other applications
792 with development builds of their framework, including the manner in which the
793 compiler changes warning behavior for system headers.
795 Framework developers can opt-in to this mechanism by creating a
796 "``.system_framework``" file at the top-level of their framework. That is, the
797 framework should have contents like:
801 .../TestFramework.framework
802 .../TestFramework.framework/.system_framework
803 .../TestFramework.framework/Headers
804 .../TestFramework.framework/Headers/TestFramework.h
807 Clang will treat the presence of this file as an indicator that the framework
808 should be treated as a system framework, regardless of how it was found in the
809 framework search path. For consistency, we recommend that such files never be
810 included in installed versions of the framework.
812 Checks for Standard Language Features
813 =====================================
815 The ``__has_feature`` macro can be used to query if certain standard language
816 features are enabled. The ``__has_extension`` macro can be used to query if
817 language features are available as an extension when compiling for a standard
818 which does not provide them. The features which can be tested are listed here.
820 Since Clang 3.4, the C++ SD-6 feature test macros are also supported.
821 These are macros with names of the form ``__cpp_<feature_name>``, and are
822 intended to be a portable way to query the supported features of the compiler.
823 See `the C++ status page <https://clang.llvm.org/cxx_status.html#ts>`_ for
824 information on the version of SD-6 supported by each Clang release, and the
825 macros provided by that revision of the recommendations.
830 The features listed below are part of the C++98 standard. These features are
831 enabled by default when compiling C++ code.
836 Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been
837 enabled. For example, compiling code with ``-fno-exceptions`` disables C++
843 Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For
844 example, compiling code with ``-fno-rtti`` disables the use of RTTI.
849 The features listed below are part of the C++11 standard. As a result, all
850 these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option
851 when compiling C++ code.
853 C++11 SFINAE includes access control
854 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
856 Use ``__has_feature(cxx_access_control_sfinae)`` or
857 ``__has_extension(cxx_access_control_sfinae)`` to determine whether
858 access-control errors (e.g., calling a private constructor) are considered to
859 be template argument deduction errors (aka SFINAE errors), per `C++ DR1170
860 <http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170>`_.
862 C++11 alias templates
863 ^^^^^^^^^^^^^^^^^^^^^
865 Use ``__has_feature(cxx_alias_templates)`` or
866 ``__has_extension(cxx_alias_templates)`` to determine if support for C++11's
867 alias declarations and alias templates is enabled.
869 C++11 alignment specifiers
870 ^^^^^^^^^^^^^^^^^^^^^^^^^^
872 Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to
873 determine if support for alignment specifiers using ``alignas`` is enabled.
875 Use ``__has_feature(cxx_alignof)`` or ``__has_extension(cxx_alignof)`` to
876 determine if support for the ``alignof`` keyword is enabled.
881 Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to
882 determine if support for attribute parsing with C++11's square bracket notation
885 C++11 generalized constant expressions
886 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
888 Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized
889 constant expressions (e.g., ``constexpr``) is enabled.
894 Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to
895 determine if support for the ``decltype()`` specifier is enabled. C++11's
896 ``decltype`` does not require type-completeness of a function call expression.
897 Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or
898 ``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if
899 support for this feature is enabled.
901 C++11 default template arguments in function templates
902 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
904 Use ``__has_feature(cxx_default_function_template_args)`` or
905 ``__has_extension(cxx_default_function_template_args)`` to determine if support
906 for default template arguments in function templates is enabled.
908 C++11 ``default``\ ed functions
909 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
911 Use ``__has_feature(cxx_defaulted_functions)`` or
912 ``__has_extension(cxx_defaulted_functions)`` to determine if support for
913 defaulted function definitions (with ``= default``) is enabled.
915 C++11 delegating constructors
916 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
918 Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for
919 delegating constructors is enabled.
921 C++11 ``deleted`` functions
922 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
924 Use ``__has_feature(cxx_deleted_functions)`` or
925 ``__has_extension(cxx_deleted_functions)`` to determine if support for deleted
926 function definitions (with ``= delete``) is enabled.
928 C++11 explicit conversion functions
929 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
931 Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for
932 ``explicit`` conversion functions is enabled.
934 C++11 generalized initializers
935 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
937 Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for
938 generalized initializers (using braced lists and ``std::initializer_list``) is
941 C++11 implicit move constructors/assignment operators
942 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
944 Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly
945 generate move constructors and move assignment operators where needed.
947 C++11 inheriting constructors
948 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
950 Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for
951 inheriting constructors is enabled.
953 C++11 inline namespaces
954 ^^^^^^^^^^^^^^^^^^^^^^^
956 Use ``__has_feature(cxx_inline_namespaces)`` or
957 ``__has_extension(cxx_inline_namespaces)`` to determine if support for inline
958 namespaces is enabled.
963 Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to
964 determine if support for lambdas is enabled.
966 C++11 local and unnamed types as template arguments
967 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
969 Use ``__has_feature(cxx_local_type_template_args)`` or
970 ``__has_extension(cxx_local_type_template_args)`` to determine if support for
971 local and unnamed types as template arguments is enabled.
976 Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to
977 determine if support for noexcept exception specifications is enabled.
979 C++11 in-class non-static data member initialization
980 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
982 Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class
983 initialization of non-static data members is enabled.
988 Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to
989 determine if support for ``nullptr`` is enabled.
991 C++11 ``override control``
992 ^^^^^^^^^^^^^^^^^^^^^^^^^^
994 Use ``__has_feature(cxx_override_control)`` or
995 ``__has_extension(cxx_override_control)`` to determine if support for the
996 override control keywords is enabled.
998 C++11 reference-qualified functions
999 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1001 Use ``__has_feature(cxx_reference_qualified_functions)`` or
1002 ``__has_extension(cxx_reference_qualified_functions)`` to determine if support
1003 for reference-qualified functions (e.g., member functions with ``&`` or ``&&``
1004 applied to ``*this``) is enabled.
1006 C++11 range-based ``for`` loop
1007 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1009 Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to
1010 determine if support for the range-based for loop is enabled.
1012 C++11 raw string literals
1013 ^^^^^^^^^^^^^^^^^^^^^^^^^
1015 Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw
1016 string literals (e.g., ``R"x(foo\bar)x"``) is enabled.
1018 C++11 rvalue references
1019 ^^^^^^^^^^^^^^^^^^^^^^^
1021 Use ``__has_feature(cxx_rvalue_references)`` or
1022 ``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue
1023 references is enabled.
1025 C++11 ``static_assert()``
1026 ^^^^^^^^^^^^^^^^^^^^^^^^^
1028 Use ``__has_feature(cxx_static_assert)`` or
1029 ``__has_extension(cxx_static_assert)`` to determine if support for compile-time
1030 assertions using ``static_assert`` is enabled.
1032 C++11 ``thread_local``
1033 ^^^^^^^^^^^^^^^^^^^^^^
1035 Use ``__has_feature(cxx_thread_local)`` to determine if support for
1036 ``thread_local`` variables is enabled.
1038 C++11 type inference
1039 ^^^^^^^^^^^^^^^^^^^^
1041 Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to
1042 determine C++11 type inference is supported using the ``auto`` specifier. If
1043 this is disabled, ``auto`` will instead be a storage class specifier, as in C
1046 C++11 strongly typed enumerations
1047 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1049 Use ``__has_feature(cxx_strong_enums)`` or
1050 ``__has_extension(cxx_strong_enums)`` to determine if support for strongly
1051 typed, scoped enumerations is enabled.
1053 C++11 trailing return type
1054 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1056 Use ``__has_feature(cxx_trailing_return)`` or
1057 ``__has_extension(cxx_trailing_return)`` to determine if support for the
1058 alternate function declaration syntax with trailing return type is enabled.
1060 C++11 Unicode string literals
1061 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1063 Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode
1064 string literals is enabled.
1066 C++11 unrestricted unions
1067 ^^^^^^^^^^^^^^^^^^^^^^^^^
1069 Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for
1070 unrestricted unions is enabled.
1072 C++11 user-defined literals
1073 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
1075 Use ``__has_feature(cxx_user_literals)`` to determine if support for
1076 user-defined literals is enabled.
1078 C++11 variadic templates
1079 ^^^^^^^^^^^^^^^^^^^^^^^^
1081 Use ``__has_feature(cxx_variadic_templates)`` or
1082 ``__has_extension(cxx_variadic_templates)`` to determine if support for
1083 variadic templates is enabled.
1088 The features listed below are part of the C++14 standard. As a result, all
1089 these features are enabled with the ``-std=C++14`` or ``-std=gnu++14`` option
1090 when compiling C++ code.
1092 C++14 binary literals
1093 ^^^^^^^^^^^^^^^^^^^^^
1095 Use ``__has_feature(cxx_binary_literals)`` or
1096 ``__has_extension(cxx_binary_literals)`` to determine whether
1097 binary literals (for instance, ``0b10010``) are recognized. Clang supports this
1098 feature as an extension in all language modes.
1100 C++14 contextual conversions
1101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1103 Use ``__has_feature(cxx_contextual_conversions)`` or
1104 ``__has_extension(cxx_contextual_conversions)`` to determine if the C++14 rules
1105 are used when performing an implicit conversion for an array bound in a
1106 *new-expression*, the operand of a *delete-expression*, an integral constant
1107 expression, or a condition in a ``switch`` statement.
1109 C++14 decltype(auto)
1110 ^^^^^^^^^^^^^^^^^^^^
1112 Use ``__has_feature(cxx_decltype_auto)`` or
1113 ``__has_extension(cxx_decltype_auto)`` to determine if support
1114 for the ``decltype(auto)`` placeholder type is enabled.
1116 C++14 default initializers for aggregates
1117 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1119 Use ``__has_feature(cxx_aggregate_nsdmi)`` or
1120 ``__has_extension(cxx_aggregate_nsdmi)`` to determine if support
1121 for default initializers in aggregate members is enabled.
1123 C++14 digit separators
1124 ^^^^^^^^^^^^^^^^^^^^^^
1126 Use ``__cpp_digit_separators`` to determine if support for digit separators
1127 using single quotes (for instance, ``10'000``) is enabled. At this time, there
1128 is no corresponding ``__has_feature`` name
1130 C++14 generalized lambda capture
1131 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1133 Use ``__has_feature(cxx_init_captures)`` or
1134 ``__has_extension(cxx_init_captures)`` to determine if support for
1135 lambda captures with explicit initializers is enabled
1136 (for instance, ``[n(0)] { return ++n; }``).
1138 C++14 generic lambdas
1139 ^^^^^^^^^^^^^^^^^^^^^
1141 Use ``__has_feature(cxx_generic_lambdas)`` or
1142 ``__has_extension(cxx_generic_lambdas)`` to determine if support for generic
1143 (polymorphic) lambdas is enabled
1144 (for instance, ``[] (auto x) { return x + 1; }``).
1146 C++14 relaxed constexpr
1147 ^^^^^^^^^^^^^^^^^^^^^^^
1149 Use ``__has_feature(cxx_relaxed_constexpr)`` or
1150 ``__has_extension(cxx_relaxed_constexpr)`` to determine if variable
1151 declarations, local variable modification, and control flow constructs
1152 are permitted in ``constexpr`` functions.
1154 C++14 return type deduction
1155 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
1157 Use ``__has_feature(cxx_return_type_deduction)`` or
1158 ``__has_extension(cxx_return_type_deduction)`` to determine if support
1159 for return type deduction for functions (using ``auto`` as a return type)
1162 C++14 runtime-sized arrays
1163 ^^^^^^^^^^^^^^^^^^^^^^^^^^
1165 Use ``__has_feature(cxx_runtime_array)`` or
1166 ``__has_extension(cxx_runtime_array)`` to determine if support
1167 for arrays of runtime bound (a restricted form of variable-length arrays)
1169 Clang's implementation of this feature is incomplete.
1171 C++14 variable templates
1172 ^^^^^^^^^^^^^^^^^^^^^^^^
1174 Use ``__has_feature(cxx_variable_templates)`` or
1175 ``__has_extension(cxx_variable_templates)`` to determine if support for
1176 templated variable declarations is enabled.
1181 The features listed below are part of the C11 standard. As a result, all these
1182 features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when
1183 compiling C code. Additionally, because these features are all
1184 backward-compatible, they are available as extensions in all language modes.
1186 C11 alignment specifiers
1187 ^^^^^^^^^^^^^^^^^^^^^^^^
1189 Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine
1190 if support for alignment specifiers using ``_Alignas`` is enabled.
1192 Use ``__has_feature(c_alignof)`` or ``__has_extension(c_alignof)`` to determine
1193 if support for the ``_Alignof`` keyword is enabled.
1195 C11 atomic operations
1196 ^^^^^^^^^^^^^^^^^^^^^
1198 Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine
1199 if support for atomic types using ``_Atomic`` is enabled. Clang also provides
1200 :ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement
1201 the ``<stdatomic.h>`` operations on ``_Atomic`` types. Use
1202 ``__has_include(<stdatomic.h>)`` to determine if C11's ``<stdatomic.h>`` header
1205 Clang will use the system's ``<stdatomic.h>`` header when one is available, and
1206 will otherwise use its own. When using its own, implementations of the atomic
1207 operations are provided as macros. In the cases where C11 also requires a real
1208 function, this header provides only the declaration of that function (along
1209 with a shadowing macro implementation), and you must link to a library which
1210 provides a definition of the function if you use it instead of the macro.
1212 C11 generic selections
1213 ^^^^^^^^^^^^^^^^^^^^^^
1215 Use ``__has_feature(c_generic_selections)`` or
1216 ``__has_extension(c_generic_selections)`` to determine if support for generic
1217 selections is enabled.
1219 As an extension, the C11 generic selection expression is available in all
1220 languages supported by Clang. The syntax is the same as that given in the C11
1223 In C, type compatibility is decided according to the rules given in the
1224 appropriate standard, but in C++, which lacks the type compatibility rules used
1225 in C, types are considered compatible only if they are equivalent.
1227 C11 ``_Static_assert()``
1228 ^^^^^^^^^^^^^^^^^^^^^^^^
1230 Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)``
1231 to determine if support for compile-time assertions using ``_Static_assert`` is
1234 C11 ``_Thread_local``
1235 ^^^^^^^^^^^^^^^^^^^^^
1237 Use ``__has_feature(c_thread_local)`` or ``__has_extension(c_thread_local)``
1238 to determine if support for ``_Thread_local`` variables is enabled.
1243 Use ``__has_feature(modules)`` to determine if Modules have been enabled.
1244 For example, compiling code with ``-fmodules`` enables the use of Modules.
1246 More information could be found `here <https://clang.llvm.org/docs/Modules.html>`_.
1248 Type Trait Primitives
1249 =====================
1251 Type trait primitives are special builtin constant expressions that can be used
1252 by the standard C++ library to facilitate or simplify the implementation of
1253 user-facing type traits in the <type_traits> header.
1255 They are not intended to be used directly by user code because they are
1256 implementation-defined and subject to change -- as such they're tied closely to
1257 the supported set of system headers, currently:
1261 * The Microsoft standard C++ library
1263 Clang supports the `GNU C++ type traits
1264 <https://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the
1265 `Microsoft Visual C++ type traits
1266 <https://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_,
1267 as well as nearly all of the
1268 `Embarcadero C++ type traits
1269 <http://docwiki.embarcadero.com/RADStudio/Rio/en/Type_Trait_Functions_(C%2B%2B11)_Index>`_.
1271 The following type trait primitives are supported by Clang. Those traits marked
1272 (C++) provide implementations for type traits specified by the C++ standard;
1273 ``__X(...)`` has the same semantics and constraints as the corresponding
1274 ``std::X_t<...>`` or ``std::X_v<...>`` type trait.
1276 * ``__array_rank(type)`` (Embarcadero):
1277 Returns the number of levels of array in the type ``type``:
1278 ``0`` if ``type`` is not an array type, and
1279 ``__array_rank(element) + 1`` if ``type`` is an array of ``element``.
1280 * ``__array_extent(type, dim)`` (Embarcadero):
1281 The ``dim``'th array bound in the type ``type``, or ``0`` if
1282 ``dim >= __array_rank(type)``.
1283 * ``__has_nothrow_assign`` (GNU, Microsoft, Embarcadero):
1284 Deprecated, use ``__is_nothrow_assignable`` instead.
1285 * ``__has_nothrow_move_assign`` (GNU, Microsoft):
1286 Deprecated, use ``__is_nothrow_assignable`` instead.
1287 * ``__has_nothrow_copy`` (GNU, Microsoft):
1288 Deprecated, use ``__is_nothrow_constructible`` instead.
1289 * ``__has_nothrow_constructor`` (GNU, Microsoft):
1290 Deprecated, use ``__is_nothrow_constructible`` instead.
1291 * ``__has_trivial_assign`` (GNU, Microsoft, Embarcadero):
1292 Deprecated, use ``__is_trivially_assignable`` instead.
1293 * ``__has_trivial_move_assign`` (GNU, Microsoft):
1294 Deprecated, use ``__is_trivially_assignable`` instead.
1295 * ``__has_trivial_copy`` (GNU, Microsoft):
1296 Deprecated, use ``__is_trivially_constructible`` instead.
1297 * ``__has_trivial_constructor`` (GNU, Microsoft):
1298 Deprecated, use ``__is_trivially_constructible`` instead.
1299 * ``__has_trivial_move_constructor`` (GNU, Microsoft):
1300 Deprecated, use ``__is_trivially_constructible`` instead.
1301 * ``__has_trivial_destructor`` (GNU, Microsoft, Embarcadero):
1302 Deprecated, use ``__is_trivially_destructible`` instead.
1303 * ``__has_unique_object_representations`` (C++, GNU)
1304 * ``__has_virtual_destructor`` (C++, GNU, Microsoft, Embarcadero)
1305 * ``__is_abstract`` (C++, GNU, Microsoft, Embarcadero)
1306 * ``__is_aggregate`` (C++, GNU, Microsoft)
1307 * ``__is_arithmetic`` (C++, Embarcadero)
1308 * ``__is_array`` (C++, Embarcadero)
1309 * ``__is_assignable`` (C++, MSVC 2015)
1310 * ``__is_base_of`` (C++, GNU, Microsoft, Embarcadero)
1311 * ``__is_class`` (C++, GNU, Microsoft, Embarcadero)
1312 * ``__is_complete_type(type)`` (Embarcadero):
1313 Return ``true`` if ``type`` is a complete type.
1314 Warning: this trait is dangerous because it can return different values at
1315 different points in the same program.
1316 * ``__is_compound`` (C++, Embarcadero)
1317 * ``__is_const`` (C++, Embarcadero)
1318 * ``__is_constructible`` (C++, MSVC 2013)
1319 * ``__is_convertible`` (C++, Embarcadero)
1320 * ``__is_convertible_to`` (Microsoft):
1321 Synonym for ``__is_convertible``.
1322 * ``__is_destructible`` (C++, MSVC 2013):
1323 Only available in ``-fms-extensions`` mode.
1324 * ``__is_empty`` (C++, GNU, Microsoft, Embarcadero)
1325 * ``__is_enum`` (C++, GNU, Microsoft, Embarcadero)
1326 * ``__is_final`` (C++, GNU, Microsoft)
1327 * ``__is_floating_point`` (C++, Embarcadero)
1328 * ``__is_function`` (C++, Embarcadero)
1329 * ``__is_fundamental`` (C++, Embarcadero)
1330 * ``__is_integral`` (C++, Embarcadero)
1331 * ``__is_interface_class`` (Microsoft):
1332 Returns ``false``, even for types defined with ``__interface``.
1333 * ``__is_literal`` (Clang):
1334 Synonym for ``__is_literal_type``.
1335 * ``__is_literal_type`` (C++, GNU, Microsoft):
1336 Note, the corresponding standard trait was deprecated in C++17
1337 and removed in C++20.
1338 * ``__is_lvalue_reference`` (C++, Embarcadero)
1339 * ``__is_member_object_pointer`` (C++, Embarcadero)
1340 * ``__is_member_function_pointer`` (C++, Embarcadero)
1341 * ``__is_member_pointer`` (C++, Embarcadero)
1342 * ``__is_nothrow_assignable`` (C++, MSVC 2013)
1343 * ``__is_nothrow_constructible`` (C++, MSVC 2013)
1344 * ``__is_nothrow_destructible`` (C++, MSVC 2013)
1345 Only available in ``-fms-extensions`` mode.
1346 * ``__is_object`` (C++, Embarcadero)
1347 * ``__is_pod`` (C++, GNU, Microsoft, Embarcadero):
1348 Note, the corresponding standard trait was deprecated in C++20.
1349 * ``__is_pointer`` (C++, Embarcadero)
1350 * ``__is_polymorphic`` (C++, GNU, Microsoft, Embarcadero)
1351 * ``__is_reference`` (C++, Embarcadero)
1352 * ``__is_rvalue_reference`` (C++, Embarcadero)
1353 * ``__is_same`` (C++, Embarcadero)
1354 * ``__is_same_as`` (GCC): Synonym for ``__is_same``.
1355 * ``__is_scalar`` (C++, Embarcadero)
1356 * ``__is_sealed`` (Microsoft):
1357 Synonym for ``__is_final``.
1358 * ``__is_signed`` (C++, Embarcadero):
1359 Returns false for enumeration types, and returns true for floating-point
1360 types. Note, before Clang 10, returned true for enumeration types if the
1361 underlying type was signed, and returned false for floating-point types.
1362 * ``__is_standard_layout`` (C++, GNU, Microsoft, Embarcadero)
1363 * ``__is_trivial`` (C++, GNU, Microsoft, Embarcadero)
1364 * ``__is_trivially_assignable`` (C++, GNU, Microsoft)
1365 * ``__is_trivially_constructible`` (C++, GNU, Microsoft)
1366 * ``__is_trivially_copyable`` (C++, GNU, Microsoft)
1367 * ``__is_trivially_destructible`` (C++, MSVC 2013)
1368 * ``__is_union`` (C++, GNU, Microsoft, Embarcadero)
1369 * ``__is_unsigned`` (C++, Embarcadero):
1370 Returns false for enumeration types. Note, before Clang 13, returned true for
1371 enumeration types if the underlying type was unsigned.
1372 * ``__is_void`` (C++, Embarcadero)
1373 * ``__is_volatile`` (C++, Embarcadero)
1374 * ``__reference_binds_to_temporary(T, U)`` (Clang): Determines whether a
1375 reference of type ``T`` bound to an expression of type ``U`` would bind to a
1376 materialized temporary object. If ``T`` is not a reference type the result
1377 is false. Note this trait will also return false when the initialization of
1378 ``T`` from ``U`` is ill-formed.
1379 * ``__underlying_type`` (C++, GNU, Microsoft)
1381 In addition, the following expression traits are supported:
1383 * ``__is_lvalue_expr(e)`` (Embarcadero):
1384 Returns true if ``e`` is an lvalue expression.
1385 Deprecated, use ``__is_lvalue_reference(decltype((e)))`` instead.
1386 * ``__is_rvalue_expr(e)`` (Embarcadero):
1387 Returns true if ``e`` is a prvalue expression.
1388 Deprecated, use ``!__is_reference(decltype((e)))`` instead.
1390 There are multiple ways to detect support for a type trait ``__X`` in the
1391 compiler, depending on the oldest version of Clang you wish to support.
1393 * From Clang 10 onwards, ``__has_builtin(__X)`` can be used.
1394 * From Clang 6 onwards, ``!__is_identifier(__X)`` can be used.
1395 * From Clang 3 onwards, ``__has_feature(X)`` can be used, but only supports
1396 the following traits:
1398 * ``__has_nothrow_assign``
1399 * ``__has_nothrow_copy``
1400 * ``__has_nothrow_constructor``
1401 * ``__has_trivial_assign``
1402 * ``__has_trivial_copy``
1403 * ``__has_trivial_constructor``
1404 * ``__has_trivial_destructor``
1405 * ``__has_virtual_destructor``
1409 * ``__is_constructible``
1410 * ``__is_convertible_to``
1415 * ``__is_standard_layout``
1417 * ``__is_polymorphic``
1420 * ``__is_trivially_assignable``
1421 * ``__is_trivially_constructible``
1422 * ``__is_trivially_copyable``
1424 * ``__underlying_type``
1426 A simplistic usage example as might be seen in standard C++ headers follows:
1430 #if __has_builtin(__is_convertible_to)
1431 template<typename From, typename To>
1432 struct is_convertible_to {
1433 static const bool value = __is_convertible_to(From, To);
1436 // Emulate type trait for compatibility with other compilers.
1442 The syntax and high level language feature description is in
1443 :doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for
1444 the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`.
1446 Query for this feature with ``__has_extension(blocks)``.
1448 ASM Goto with Output Constraints
1449 ================================
1451 In addition to the functionality provided by `GCC's extended
1452 assembly <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_, clang
1453 supports output constraints with the `goto` form.
1455 The goto form of GCC's extended assembly allows the programmer to branch to a C
1456 label from within an inline assembly block. Clang extends this behavior by
1457 allowing the programmer to use output constraints:
1463 asm goto("# %0 %1 %l2" : "=r"(y) : "r"(x) : : err);
1469 It's important to note that outputs are valid only on the "fallthrough" branch.
1470 Using outputs on an indirect branch may result in undefined behavior. For
1471 example, in the function above, use of the value assigned to `y` in the `err`
1472 block is undefined behavior.
1474 Query for this feature with ``__has_extension(gnu_asm_goto_with_outputs)``.
1476 Objective-C Features
1477 ====================
1479 Related result types
1480 --------------------
1482 According to Cocoa conventions, Objective-C methods with certain names
1483 ("``init``", "``alloc``", etc.) always return objects that are an instance of
1484 the receiving class's type. Such methods are said to have a "related result
1485 type", meaning that a message send to one of these methods will have the same
1486 static type as an instance of the receiver class. For example, given the
1489 .. code-block:: objc
1496 @interface NSArray : NSObject
1499 and this common initialization pattern
1501 .. code-block:: objc
1503 NSArray *array = [[NSArray alloc] init];
1505 the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because
1506 ``alloc`` implicitly has a related result type. Similarly, the type of the
1507 expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a
1508 related result type and its receiver is known to have the type ``NSArray *``.
1509 If neither ``alloc`` nor ``init`` had a related result type, the expressions
1510 would have had type ``id``, as declared in the method signature.
1512 A method with a related result type can be declared by using the type
1513 ``instancetype`` as its result type. ``instancetype`` is a contextual keyword
1514 that is only permitted in the result type of an Objective-C method, e.g.
1516 .. code-block:: objc
1519 + (instancetype)constructAnA;
1522 The related result type can also be inferred for some methods. To determine
1523 whether a method has an inferred related result type, the first word in the
1524 camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered,
1525 and the method will have a related result type if its return type is compatible
1526 with the type of its class and if:
1528 * the first word is "``alloc``" or "``new``", and the method is a class method,
1531 * the first word is "``autorelease``", "``init``", "``retain``", or "``self``",
1532 and the method is an instance method.
1534 If a method with a related result type is overridden by a subclass method, the
1535 subclass method must also return a type that is compatible with the subclass
1538 .. code-block:: objc
1540 @interface NSString : NSObject
1541 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
1544 Related result types only affect the type of a message send or property access
1545 via the given method. In all other respects, a method with a related result
1546 type is treated the same way as method that returns ``id``.
1548 Use ``__has_feature(objc_instancetype)`` to determine whether the
1549 ``instancetype`` contextual keyword is available.
1551 Automatic reference counting
1552 ----------------------------
1554 Clang provides support for :doc:`automated reference counting
1555 <AutomaticReferenceCounting>` in Objective-C, which eliminates the need
1556 for manual ``retain``/``release``/``autorelease`` message sends. There are three
1557 feature macros associated with automatic reference counting:
1558 ``__has_feature(objc_arc)`` indicates the availability of automated reference
1559 counting in general, while ``__has_feature(objc_arc_weak)`` indicates that
1560 automated reference counting also includes support for ``__weak`` pointers to
1561 Objective-C objects. ``__has_feature(objc_arc_fields)`` indicates that C structs
1562 are allowed to have fields that are pointers to Objective-C objects managed by
1563 automatic reference counting.
1570 Clang supports ARC-style weak and unsafe references in Objective-C even
1571 outside of ARC mode. Weak references must be explicitly enabled with
1572 the ``-fobjc-weak`` option; use ``__has_feature((objc_arc_weak))``
1573 to test whether they are enabled. Unsafe references are enabled
1574 unconditionally. ARC-style weak and unsafe references cannot be used
1575 when Objective-C garbage collection is enabled.
1577 Except as noted below, the language rules for the ``__weak`` and
1578 ``__unsafe_unretained`` qualifiers (and the ``weak`` and
1579 ``unsafe_unretained`` property attributes) are just as laid out
1580 in the :doc:`ARC specification <AutomaticReferenceCounting>`.
1581 In particular, note that some classes do not support forming weak
1582 references to their instances, and note that special care must be
1583 taken when storing weak references in memory where initialization
1584 and deinitialization are outside the responsibility of the compiler
1585 (such as in ``malloc``-ed memory).
1587 Loading from a ``__weak`` variable always implicitly retains the
1588 loaded value. In non-ARC modes, this retain is normally balanced
1589 by an implicit autorelease. This autorelease can be suppressed
1590 by performing the load in the receiver position of a ``-retain``
1591 message send (e.g. ``[weakReference retain]``); note that this performs
1592 only a single retain (the retain done when primitively loading from
1593 the weak reference).
1595 For the most part, ``__unsafe_unretained`` in non-ARC modes is just the
1596 default behavior of variables and therefore is not needed. However,
1597 it does have an effect on the semantics of block captures: normally,
1598 copying a block which captures an Objective-C object or block pointer
1599 causes the captured pointer to be retained or copied, respectively,
1600 but that behavior is suppressed when the captured variable is qualified
1601 with ``__unsafe_unretained``.
1603 Note that the ``__weak`` qualifier formerly meant the GC qualifier in
1604 all non-ARC modes and was silently ignored outside of GC modes. It now
1605 means the ARC-style qualifier in all non-GC modes and is no longer
1606 allowed if not enabled by either ``-fobjc-arc`` or ``-fobjc-weak``.
1607 It is expected that ``-fobjc-weak`` will eventually be enabled by default
1608 in all non-GC Objective-C modes.
1610 .. _objc-fixed-enum:
1612 Enumerations with a fixed underlying type
1613 -----------------------------------------
1615 Clang provides support for C++11 enumerations with a fixed underlying type
1616 within Objective-C. For example, one can write an enumeration type as:
1620 typedef enum : unsigned char { Red, Green, Blue } Color;
1622 This specifies that the underlying type, which is used to store the enumeration
1623 value, is ``unsigned char``.
1625 Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed
1626 underlying types is available in Objective-C.
1628 Interoperability with C++11 lambdas
1629 -----------------------------------
1631 Clang provides interoperability between C++11 lambdas and blocks-based APIs, by
1632 permitting a lambda to be implicitly converted to a block pointer with the
1633 corresponding signature. For example, consider an API such as ``NSArray``'s
1634 array-sorting method:
1636 .. code-block:: objc
1638 - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr;
1640 ``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult
1641 (^)(id, id)``, and parameters of this type are generally provided with block
1642 literals as arguments. However, one can also use a C++11 lambda so long as it
1643 provides the same signature (in this case, accepting two parameters of type
1644 ``id`` and returning an ``NSComparisonResult``):
1646 .. code-block:: objc
1648 NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11",
1650 const NSStringCompareOptions comparisonOptions
1651 = NSCaseInsensitiveSearch | NSNumericSearch |
1652 NSWidthInsensitiveSearch | NSForcedOrderingSearch;
1653 NSLocale *currentLocale = [NSLocale currentLocale];
1655 = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult {
1656 NSRange string1Range = NSMakeRange(0, [s1 length]);
1657 return [s1 compare:s2 options:comparisonOptions
1658 range:string1Range locale:currentLocale];
1660 NSLog(@"sorted: %@", sorted);
1662 This code relies on an implicit conversion from the type of the lambda
1663 expression (an unnamed, local class type called the *closure type*) to the
1664 corresponding block pointer type. The conversion itself is expressed by a
1665 conversion operator in that closure type that produces a block pointer with the
1666 same signature as the lambda itself, e.g.,
1668 .. code-block:: objc
1670 operator NSComparisonResult (^)(id, id)() const;
1672 This conversion function returns a new block that simply forwards the two
1673 parameters to the lambda object (which it captures by copy), then returns the
1674 result. The returned block is first copied (with ``Block_copy``) and then
1675 autoreleased. As an optimization, if a lambda expression is immediately
1676 converted to a block pointer (as in the first example, above), then the block
1677 is not copied and autoreleased: rather, it is given the same lifetime as a
1678 block literal written at that point in the program, which avoids the overhead
1679 of copying a block to the heap in the common case.
1681 The conversion from a lambda to a block pointer is only available in
1682 Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory
1683 management (autorelease).
1685 Object Literals and Subscripting
1686 --------------------------------
1688 Clang provides support for :doc:`Object Literals and Subscripting
1689 <ObjectiveCLiterals>` in Objective-C, which simplifies common Objective-C
1690 programming patterns, makes programs more concise, and improves the safety of
1691 container creation. There are several feature macros associated with object
1692 literals and subscripting: ``__has_feature(objc_array_literals)`` tests the
1693 availability of array literals; ``__has_feature(objc_dictionary_literals)``
1694 tests the availability of dictionary literals;
1695 ``__has_feature(objc_subscripting)`` tests the availability of object
1698 Objective-C Autosynthesis of Properties
1699 ---------------------------------------
1701 Clang provides support for autosynthesis of declared properties. Using this
1702 feature, clang provides default synthesis of those properties not declared
1703 @dynamic and not having user provided backing getter and setter methods.
1704 ``__has_feature(objc_default_synthesize_properties)`` checks for availability
1705 of this feature in version of clang being used.
1707 .. _langext-objc-retain-release:
1709 Objective-C retaining behavior attributes
1710 -----------------------------------------
1712 In Objective-C, functions and methods are generally assumed to follow the
1713 `Cocoa Memory Management
1714 <https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_
1715 conventions for ownership of object arguments and
1716 return values. However, there are exceptions, and so Clang provides attributes
1717 to allow these exceptions to be documented. This are used by ARC and the
1718 `static analyzer <https://clang-analyzer.llvm.org>`_ Some exceptions may be
1719 better described using the ``objc_method_family`` attribute instead.
1721 **Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``,
1722 ``ns_returns_autoreleased``, ``cf_returns_retained``, and
1723 ``cf_returns_not_retained`` attributes can be placed on methods and functions
1724 that return Objective-C or CoreFoundation objects. They are commonly placed at
1725 the end of a function prototype or method declaration:
1727 .. code-block:: objc
1729 id foo() __attribute__((ns_returns_retained));
1731 - (NSString *)bar:(int)x __attribute__((ns_returns_retained));
1733 The ``*_returns_retained`` attributes specify that the returned object has a +1
1734 retain count. The ``*_returns_not_retained`` attributes specify that the return
1735 object has a +0 retain count, even if the normal convention for its selector
1736 would be +1. ``ns_returns_autoreleased`` specifies that the returned object is
1737 +0, but is guaranteed to live at least as long as the next flush of an
1740 **Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on
1741 an parameter declaration; they specify that the argument is expected to have a
1742 +1 retain count, which will be balanced in some way by the function or method.
1743 The ``ns_consumes_self`` attribute can only be placed on an Objective-C
1744 method; it specifies that the method expects its ``self`` parameter to have a
1745 +1 retain count, which it will balance in some way.
1747 .. code-block:: objc
1749 void foo(__attribute__((ns_consumed)) NSString *string);
1751 - (void) bar __attribute__((ns_consumes_self));
1752 - (void) baz:(id) __attribute__((ns_consumed)) x;
1754 Further examples of these attributes are available in the static analyzer's `list of annotations for analysis
1755 <https://clang-analyzer.llvm.org/annotations.html#cocoa_mem>`_.
1757 Query for these features with ``__has_attribute(ns_consumed)``,
1758 ``__has_attribute(ns_returns_retained)``, etc.
1760 Objective-C @available
1761 ----------------------
1763 It is possible to use the newest SDK but still build a program that can run on
1764 older versions of macOS and iOS by passing ``-mmacosx-version-min=`` /
1765 ``-miphoneos-version-min=``.
1767 Before LLVM 5.0, when calling a function that exists only in the OS that's
1768 newer than the target OS (as determined by the minimum deployment version),
1769 programmers had to carefully check if the function exists at runtime, using
1770 null checks for weakly-linked C functions, ``+class`` for Objective-C classes,
1771 and ``-respondsToSelector:`` or ``+instancesRespondToSelector:`` for
1772 Objective-C methods. If such a check was missed, the program would compile
1773 fine, run fine on newer systems, but crash on older systems.
1775 As of LLVM 5.0, ``-Wunguarded-availability`` uses the `availability attributes
1776 <https://clang.llvm.org/docs/AttributeReference.html#availability>`_ together
1777 with the new ``@available()`` keyword to assist with this issue.
1778 When a method that's introduced in the OS newer than the target OS is called, a
1779 -Wunguarded-availability warning is emitted if that call is not guarded:
1781 .. code-block:: objc
1783 void my_fun(NSSomeClass* var) {
1784 // If fancyNewMethod was added in e.g. macOS 10.12, but the code is
1785 // built with -mmacosx-version-min=10.11, then this unconditional call
1786 // will emit a -Wunguarded-availability warning:
1787 [var fancyNewMethod];
1790 To fix the warning and to avoid the crash on macOS 10.11, wrap it in
1791 ``if(@available())``:
1793 .. code-block:: objc
1795 void my_fun(NSSomeClass* var) {
1796 if (@available(macOS 10.12, *)) {
1797 [var fancyNewMethod];
1799 // Put fallback behavior for old macOS versions (and for non-mac
1804 The ``*`` is required and means that platforms not explicitly listed will take
1805 the true branch, and the compiler will emit ``-Wunguarded-availability``
1806 warnings for unlisted platforms based on those platform's deployment target.
1807 More than one platform can be listed in ``@available()``:
1809 .. code-block:: objc
1811 void my_fun(NSSomeClass* var) {
1812 if (@available(macOS 10.12, iOS 10, *)) {
1813 [var fancyNewMethod];
1817 If the caller of ``my_fun()`` already checks that ``my_fun()`` is only called
1818 on 10.12, then add an `availability attribute
1819 <https://clang.llvm.org/docs/AttributeReference.html#availability>`_ to it,
1820 which will also suppress the warning and require that calls to my_fun() are
1823 .. code-block:: objc
1825 API_AVAILABLE(macos(10.12)) void my_fun(NSSomeClass* var) {
1826 [var fancyNewMethod]; // Now ok.
1829 ``@available()`` is only available in Objective-C code. To use the feature
1830 in C and C++ code, use the ``__builtin_available()`` spelling instead.
1832 If existing code uses null checks or ``-respondsToSelector:``, it should
1833 be changed to use ``@available()`` (or ``__builtin_available``) instead.
1835 ``-Wunguarded-availability`` is disabled by default, but
1836 ``-Wunguarded-availability-new``, which only emits this warning for APIs
1837 that have been introduced in macOS >= 10.13, iOS >= 11, watchOS >= 4 and
1838 tvOS >= 11, is enabled by default.
1840 .. _langext-overloading:
1842 Objective-C++ ABI: protocol-qualifier mangling of parameters
1843 ------------------------------------------------------------
1845 Starting with LLVM 3.4, Clang produces a new mangling for parameters whose
1846 type is a qualified-``id`` (e.g., ``id<Foo>``). This mangling allows such
1847 parameters to be differentiated from those with the regular unqualified ``id``
1850 This was a non-backward compatible mangling change to the ABI. This change
1851 allows proper overloading, and also prevents mangling conflicts with template
1852 parameters of protocol-qualified type.
1854 Query the presence of this new mangling with
1855 ``__has_feature(objc_protocol_qualifier_mangling)``.
1857 Initializer lists for complex numbers in C
1858 ==========================================
1860 clang supports an extension which allows the following in C:
1865 #include <complex.h>
1866 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf)
1868 This construct is useful because there is no way to separately initialize the
1869 real and imaginary parts of a complex variable in standard C, given that clang
1870 does not support ``_Imaginary``. (Clang also supports the ``__real__`` and
1871 ``__imag__`` extensions from gcc, which help in some cases, but are not usable
1872 in static initializers.)
1874 Note that this extension does not allow eliding the braces; the meaning of the
1875 following two lines is different:
1879 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1)
1880 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0)
1882 This extension also works in C++ mode, as far as that goes, but does not apply
1883 to the C++ ``std::complex``. (In C++11, list initialization allows the same
1884 syntax to be used with ``std::complex`` with the same meaning.)
1886 For GCC compatibility, ``__builtin_complex(re, im)`` can also be used to
1887 construct a complex number from the given real and imaginary components.
1892 Clang supports internal OpenCL extensions documented below.
1894 ``__cl_clang_bitfields``
1895 --------------------------------
1897 With this extension it is possible to enable bitfields in structs
1898 or unions using the OpenCL extension pragma mechanism detailed in
1899 `the OpenCL Extension Specification, section 1.2
1900 <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_.
1902 Use of bitfields in OpenCL kernels can result in reduced portability as struct
1903 layout is not guaranteed to be consistent when compiled by different compilers.
1904 If structs with bitfields are used as kernel function parameters, it can result
1905 in incorrect functionality when the layout is different between the host and
1912 #pragma OPENCL EXTENSION __cl_clang_bitfields : enable
1913 struct with_bitfield {
1914 unsigned int i : 5; // compiled - no diagnostic generated
1917 #pragma OPENCL EXTENSION __cl_clang_bitfields : disable
1918 struct without_bitfield {
1919 unsigned int i : 5; // error - bitfields are not supported
1922 ``__cl_clang_function_pointers``
1923 --------------------------------
1925 With this extension it is possible to enable various language features that
1926 are relying on function pointers using regular OpenCL extension pragma
1927 mechanism detailed in `the OpenCL Extension Specification,
1929 <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_.
1931 In C++ for OpenCL this also enables:
1933 - Use of member function pointers;
1935 - Unrestricted use of references to functions;
1937 - Virtual member functions.
1939 Such functionality is not conformant and does not guarantee to compile
1940 correctly in any circumstances. It can be used if:
1942 - the kernel source does not contain call expressions to (member-) function
1943 pointers, or virtual functions. For example this extension can be used in
1944 metaprogramming algorithms to be able to specify/detect types generically.
1946 - the generated kernel binary does not contain indirect calls because they
1947 are eliminated using compiler optimizations e.g. devirtualization.
1949 - the selected target supports the function pointer like functionality e.g.
1956 #pragma OPENCL EXTENSION __cl_clang_function_pointers : enable
1959 void (*fp)(); // compiled - no diagnostic generated
1962 #pragma OPENCL EXTENSION __cl_clang_function_pointers : disable
1965 void (*fp)(); // error - pointers to function are not allowed
1968 ``__cl_clang_variadic_functions``
1969 ---------------------------------
1971 With this extension it is possible to enable variadic arguments in functions
1972 using regular OpenCL extension pragma mechanism detailed in `the OpenCL
1973 Extension Specification, section 1.2
1974 <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_.
1976 This is not conformant behavior and it can only be used portably when the
1977 functions with variadic prototypes do not get generated in binary e.g. the
1978 variadic prototype is used to specify a function type with any number of
1979 arguments in metaprogramming algorithms in C++ for OpenCL.
1981 This extensions can also be used when the kernel code is intended for targets
1982 supporting the variadic arguments e.g. majority of CPU targets.
1988 #pragma OPENCL EXTENSION __cl_clang_variadic_functions : enable
1989 void foo(int a, ...); // compiled - no diagnostic generated
1991 #pragma OPENCL EXTENSION __cl_clang_variadic_functions : disable
1992 void bar(int a, ...); // error - variadic prototype is not allowed
1994 ``__cl_clang_non_portable_kernel_param_types``
1995 ----------------------------------------------
1997 With this extension it is possible to enable the use of some restricted types
1998 in kernel parameters specified in `C++ for OpenCL v1.0 s2.4
1999 <https://www.khronos.org/opencl/assets/CXX_for_OpenCL.html#kernel_function>`_.
2000 The restrictions can be relaxed using regular OpenCL extension pragma mechanism
2001 detailed in `the OpenCL Extension Specification, section 1.2
2002 <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_.
2004 This is not a conformant behavior and it can only be used when the
2005 kernel arguments are not accessed on the host side or the data layout/size
2006 between the host and device is known to be compatible.
2012 // Plain Old Data type.
2018 // Not POD type because of the constructor.
2019 // Standard layout type because there is only one access control.
2023 NotPod() : a(0), b(0) {}
2026 // Not standard layout type because of two different access controls.
2033 kernel void kernel_main(
2035 #pragma OPENCL EXTENSION __cl_clang_non_portable_kernel_param_types : enable
2038 #pragma OPENCL EXTENSION __cl_clang_non_portable_kernel_param_types : disable
2042 Remove address space builtin function
2043 -------------------------------------
2045 ``__remove_address_space`` allows to derive types in C++ for OpenCL
2046 that have address space qualifiers removed. This utility only affects
2047 address space qualifiers, therefore, other type qualifiers such as
2048 ``const`` or ``volatile`` remain unchanged.
2054 template<typename T>
2056 T var1; // error - local function variable with global address space
2057 __private T var2; // error - conflicting address space qualifiers
2058 __private __remove_address_space<T>::type var3; // var3 is __private int
2066 Legacy 1.x atomics with generic address space
2067 ---------------------------------------------
2069 Clang allows use of atomic functions from the OpenCL 1.x standards
2070 with the generic address space pointer in C++ for OpenCL mode.
2072 This is a non-portable feature and might not be supported by all
2079 void foo(__generic volatile unsigned int* a) {
2086 Clang supports a number of builtin library functions with the same syntax as
2087 GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``,
2088 ``__builtin_choose_expr``, ``__builtin_types_compatible_p``,
2089 ``__builtin_assume_aligned``, ``__sync_fetch_and_add``, etc. In addition to
2090 the GCC builtins, Clang supports a number of builtins that GCC does not, which
2093 Please note that Clang does not and will not support all of the GCC builtins
2094 for vector operations. Instead of using builtins, you should use the functions
2095 defined in target-specific header files like ``<xmmintrin.h>``, which define
2096 portable wrappers for these. Many of the Clang versions of these functions are
2097 implemented directly in terms of :ref:`extended vector support
2098 <langext-vectors>` instead of builtins, in order to reduce the number of
2099 builtins that we need to implement.
2101 .. _langext-__builtin_assume:
2103 ``__builtin_assume``
2104 ------------------------------
2106 ``__builtin_assume`` is used to provide the optimizer with a boolean
2107 invariant that is defined to be true.
2113 __builtin_assume(bool)
2120 __builtin_assume(x != 0);
2122 // The optimizer may short-circuit this check using the invariant.
2124 return do_something();
2126 return do_something_else();
2131 The boolean argument to this function is defined to be true. The optimizer may
2132 analyze the form of the expression provided as the argument and deduce from
2133 that information used to optimize the program. If the condition is violated
2134 during execution, the behavior is undefined. The argument itself is never
2135 evaluated, so any side effects of the expression will be discarded.
2137 Query for this feature with ``__has_builtin(__builtin_assume)``.
2139 ``__builtin_readcyclecounter``
2140 ------------------------------
2142 ``__builtin_readcyclecounter`` is used to access the cycle counter register (or
2143 a similar low-latency, high-accuracy clock) on those targets that support it.
2149 __builtin_readcyclecounter()
2155 unsigned long long t0 = __builtin_readcyclecounter();
2157 unsigned long long t1 = __builtin_readcyclecounter();
2158 unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow
2162 The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value,
2163 which may be either global or process/thread-specific depending on the target.
2164 As the backing counters often overflow quickly (on the order of seconds) this
2165 should only be used for timing small intervals. When not supported by the
2166 target, the return value is always zero. This builtin takes no arguments and
2167 produces an unsigned long long result.
2169 Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``. Note
2170 that even if present, its use may depend on run-time privilege or other OS
2173 ``__builtin_dump_struct``
2174 -------------------------
2180 __builtin_dump_struct(&some_struct, &some_printf_func);
2194 void func(struct S *s) {
2195 __builtin_dump_struct(s, &printf);
2200 .. code-block:: none
2206 struct T t : struct T {
2213 The '``__builtin_dump_struct``' function is used to print the fields of a simple
2214 structure and their values for debugging purposes. The builtin accepts a pointer
2215 to a structure to dump the fields of, and a pointer to a formatted output
2216 function whose signature must be: ``int (*)(const char *, ...)`` and must
2217 support the format specifiers used by ``printf()``.
2219 .. _langext-__builtin_shufflevector:
2221 ``__builtin_shufflevector``
2222 ---------------------------
2224 ``__builtin_shufflevector`` is used to express generic vector
2225 permutation/shuffle/swizzle operations. This builtin is also very important
2226 for the implementation of various target-specific header files like
2233 __builtin_shufflevector(vec1, vec2, index1, index2, ...)
2239 // identity operation - return 4-element vector v1.
2240 __builtin_shufflevector(v1, v1, 0, 1, 2, 3)
2242 // "Splat" element 0 of V1 into a 4-element result.
2243 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
2245 // Reverse 4-element vector V1.
2246 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
2248 // Concatenate every other element of 4-element vectors V1 and V2.
2249 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
2251 // Concatenate every other element of 8-element vectors V1 and V2.
2252 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
2254 // Shuffle v1 with some elements being undefined
2255 __builtin_shufflevector(v1, v1, 3, -1, 1, -1)
2259 The first two arguments to ``__builtin_shufflevector`` are vectors that have
2260 the same element type. The remaining arguments are a list of integers that
2261 specify the elements indices of the first two vectors that should be extracted
2262 and returned in a new vector. These element indices are numbered sequentially
2263 starting with the first vector, continuing into the second vector. Thus, if
2264 ``vec1`` is a 4-element vector, index 5 would refer to the second element of
2265 ``vec2``. An index of -1 can be used to indicate that the corresponding element
2266 in the returned vector is a don't care and can be optimized by the backend.
2268 The result of ``__builtin_shufflevector`` is a vector with the same element
2269 type as ``vec1``/``vec2`` but that has an element count equal to the number of
2272 Query for this feature with ``__has_builtin(__builtin_shufflevector)``.
2274 .. _langext-__builtin_convertvector:
2276 ``__builtin_convertvector``
2277 ---------------------------
2279 ``__builtin_convertvector`` is used to express generic vector
2280 type-conversion operations. The input vector and the output vector
2281 type must have the same number of elements.
2287 __builtin_convertvector(src_vec, dst_vec_type)
2293 typedef double vector4double __attribute__((__vector_size__(32)));
2294 typedef float vector4float __attribute__((__vector_size__(16)));
2295 typedef short vector4short __attribute__((__vector_size__(8)));
2296 vector4float vf; vector4short vs;
2298 // convert from a vector of 4 floats to a vector of 4 doubles.
2299 __builtin_convertvector(vf, vector4double)
2301 (vector4double) { (double) vf[0], (double) vf[1], (double) vf[2], (double) vf[3] }
2303 // convert from a vector of 4 shorts to a vector of 4 floats.
2304 __builtin_convertvector(vs, vector4float)
2306 (vector4float) { (float) vs[0], (float) vs[1], (float) vs[2], (float) vs[3] }
2310 The first argument to ``__builtin_convertvector`` is a vector, and the second
2311 argument is a vector type with the same number of elements as the first
2314 The result of ``__builtin_convertvector`` is a vector with the same element
2315 type as the second argument, with a value defined in terms of the action of a
2316 C-style cast applied to each element of the first argument.
2318 Query for this feature with ``__has_builtin(__builtin_convertvector)``.
2320 ``__builtin_bitreverse``
2321 ------------------------
2323 * ``__builtin_bitreverse8``
2324 * ``__builtin_bitreverse16``
2325 * ``__builtin_bitreverse32``
2326 * ``__builtin_bitreverse64``
2332 __builtin_bitreverse32(x)
2338 uint8_t rev_x = __builtin_bitreverse8(x);
2339 uint16_t rev_x = __builtin_bitreverse16(x);
2340 uint32_t rev_y = __builtin_bitreverse32(y);
2341 uint64_t rev_z = __builtin_bitreverse64(z);
2345 The '``__builtin_bitreverse``' family of builtins is used to reverse
2346 the bitpattern of an integer value; for example ``0b10110110`` becomes
2347 ``0b01101101``. These builtins can be used within constant expressions.
2349 ``__builtin_rotateleft``
2350 ------------------------
2352 * ``__builtin_rotateleft8``
2353 * ``__builtin_rotateleft16``
2354 * ``__builtin_rotateleft32``
2355 * ``__builtin_rotateleft64``
2361 __builtin_rotateleft32(x, y)
2367 uint8_t rot_x = __builtin_rotateleft8(x, y);
2368 uint16_t rot_x = __builtin_rotateleft16(x, y);
2369 uint32_t rot_x = __builtin_rotateleft32(x, y);
2370 uint64_t rot_x = __builtin_rotateleft64(x, y);
2374 The '``__builtin_rotateleft``' family of builtins is used to rotate
2375 the bits in the first argument by the amount in the second argument.
2376 For example, ``0b10000110`` rotated left by 11 becomes ``0b00110100``.
2377 The shift value is treated as an unsigned amount modulo the size of
2378 the arguments. Both arguments and the result have the bitwidth specified
2379 by the name of the builtin. These builtins can be used within constant
2382 ``__builtin_rotateright``
2383 -------------------------
2385 * ``__builtin_rotateright8``
2386 * ``__builtin_rotateright16``
2387 * ``__builtin_rotateright32``
2388 * ``__builtin_rotateright64``
2394 __builtin_rotateright32(x, y)
2400 uint8_t rot_x = __builtin_rotateright8(x, y);
2401 uint16_t rot_x = __builtin_rotateright16(x, y);
2402 uint32_t rot_x = __builtin_rotateright32(x, y);
2403 uint64_t rot_x = __builtin_rotateright64(x, y);
2407 The '``__builtin_rotateright``' family of builtins is used to rotate
2408 the bits in the first argument by the amount in the second argument.
2409 For example, ``0b10000110`` rotated right by 3 becomes ``0b11010000``.
2410 The shift value is treated as an unsigned amount modulo the size of
2411 the arguments. Both arguments and the result have the bitwidth specified
2412 by the name of the builtin. These builtins can be used within constant
2415 ``__builtin_unreachable``
2416 -------------------------
2418 ``__builtin_unreachable`` is used to indicate that a specific point in the
2419 program cannot be reached, even if the compiler might otherwise think it can.
2420 This is useful to improve optimization and eliminates certain warnings. For
2421 example, without the ``__builtin_unreachable`` in the example below, the
2422 compiler assumes that the inline asm can fall through and prints a "function
2423 declared '``noreturn``' should not return" warning.
2429 __builtin_unreachable()
2435 void myabort(void) __attribute__((noreturn));
2436 void myabort(void) {
2438 __builtin_unreachable();
2443 The ``__builtin_unreachable()`` builtin has completely undefined behavior.
2444 Since it has undefined behavior, it is a statement that it is never reached and
2445 the optimizer can take advantage of this to produce better code. This builtin
2446 takes no arguments and produces a void result.
2448 Query for this feature with ``__has_builtin(__builtin_unreachable)``.
2450 ``__builtin_unpredictable``
2451 ---------------------------
2453 ``__builtin_unpredictable`` is used to indicate that a branch condition is
2454 unpredictable by hardware mechanisms such as branch prediction logic.
2460 __builtin_unpredictable(long long)
2466 if (__builtin_unpredictable(x > 0)) {
2472 The ``__builtin_unpredictable()`` builtin is expected to be used with control
2473 flow conditions such as in ``if`` and ``switch`` statements.
2475 Query for this feature with ``__has_builtin(__builtin_unpredictable)``.
2480 ``__sync_swap`` is used to atomically swap integers or pointers in memory.
2486 type __sync_swap(type *ptr, type value, ...)
2492 int old_value = __sync_swap(&value, new_value);
2496 The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of
2497 atomic intrinsics to allow code to atomically swap the current value with the
2498 new value. More importantly, it helps developers write more efficient and
2499 correct code by avoiding expensive loops around
2500 ``__sync_bool_compare_and_swap()`` or relying on the platform specific
2501 implementation details of ``__sync_lock_test_and_set()``. The
2502 ``__sync_swap()`` builtin is a full barrier.
2504 ``__builtin_addressof``
2505 -----------------------
2507 ``__builtin_addressof`` performs the functionality of the built-in ``&``
2508 operator, ignoring any ``operator&`` overload. This is useful in constant
2509 expressions in C++11, where there is no other way to take the address of an
2510 object that overloads ``operator&``.
2516 template<typename T> constexpr T *addressof(T &value) {
2517 return __builtin_addressof(value);
2520 ``__builtin_operator_new`` and ``__builtin_operator_delete``
2521 ------------------------------------------------------------
2523 A call to ``__builtin_operator_new(args)`` is exactly the same as a call to
2524 ``::operator new(args)``, except that it allows certain optimizations
2525 that the C++ standard does not permit for a direct function call to
2526 ``::operator new`` (in particular, removing ``new`` / ``delete`` pairs and
2527 merging allocations), and that the call is required to resolve to a
2528 `replaceable global allocation function
2529 <https://en.cppreference.com/w/cpp/memory/new/operator_new>`_.
2531 Likewise, ``__builtin_operator_delete`` is exactly the same as a call to
2532 ``::operator delete(args)``, except that it permits optimizations
2533 and that the call is required to resolve to a
2534 `replaceable global deallocation function
2535 <https://en.cppreference.com/w/cpp/memory/new/operator_delete>`_.
2537 These builtins are intended for use in the implementation of ``std::allocator``
2538 and other similar allocation libraries, and are only available in C++.
2540 Query for this feature with ``__has_builtin(__builtin_operator_new)`` or
2541 ``__has_builtin(__builtin_operator_delete)``:
2543 * If the value is at least ``201802L``, the builtins behave as described above.
2545 * If the value is non-zero, the builtins may not support calling arbitrary
2546 replaceable global (de)allocation functions, but do support calling at least
2547 ``::operator new(size_t)`` and ``::operator delete(void*)``.
2549 ``__builtin_preserve_access_index``
2550 -----------------------------------
2552 ``__builtin_preserve_access_index`` specifies a code section where
2553 array subscript access and structure/union member access are relocatable
2554 under bpf compile-once run-everywhere framework. Debuginfo (typically
2555 with ``-g``) is needed, otherwise, the compiler will exit with an error.
2556 The return type for the intrinsic is the same as the type of the
2563 type __builtin_preserve_access_index(type arg)
2578 int *pb =__builtin_preserve_access_index(&v->c[3].b);
2579 __builtin_preserve_access_index(v->j);
2581 ``__builtin_sycl_unique_stable_name``
2582 -------------------------------------
2584 ``__builtin_sycl_unique_stable_name()`` is a builtin that takes a type and
2585 produces a string literal containing a unique name for the type that is stable
2586 across split compilations, mainly to support SYCL/Data Parallel C++ language.
2588 In cases where the split compilation needs to share a unique token for a type
2589 across the boundary (such as in an offloading situation), this name can be used
2590 for lookup purposes, such as in the SYCL Integration Header.
2592 The value of this builtin is computed entirely at compile time, so it can be
2593 used in constant expressions. This value encodes lambda functions based on a
2594 stable numbering order in which they appear in their local declaration contexts.
2595 Once this builtin is evaluated in a constexpr context, it is erroneous to use
2596 it in an instantiation which changes its value.
2598 In order to produce the unique name, the current implementation of the bultin
2599 uses Itanium mangling even if the host compilation uses a different name
2600 mangling scheme at runtime. The mangler marks all the lambdas required to name
2601 the SYCL kernel and emits a stable local ordering of the respective lambdas.
2602 The resulting pattern is demanglable. When non-lambda types are passed to the
2603 builtin, the mangler emits their usual pattern without any special treatment.
2609 // Computes a unique stable name for the given type.
2610 constexpr const char * __builtin_sycl_unique_stable_name( type-id );
2612 Multiprecision Arithmetic Builtins
2613 ----------------------------------
2615 Clang provides a set of builtins which expose multiprecision arithmetic in a
2616 manner amenable to C. They all have the following form:
2620 unsigned x = ..., y = ..., carryin = ..., carryout;
2621 unsigned sum = __builtin_addc(x, y, carryin, &carryout);
2623 Thus one can form a multiprecision addition chain in the following manner:
2627 unsigned *x, *y, *z, carryin=0, carryout;
2628 z[0] = __builtin_addc(x[0], y[0], carryin, &carryout);
2630 z[1] = __builtin_addc(x[1], y[1], carryin, &carryout);
2632 z[2] = __builtin_addc(x[2], y[2], carryin, &carryout);
2634 z[3] = __builtin_addc(x[3], y[3], carryin, &carryout);
2636 The complete list of builtins are:
2640 unsigned char __builtin_addcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout);
2641 unsigned short __builtin_addcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout);
2642 unsigned __builtin_addc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout);
2643 unsigned long __builtin_addcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout);
2644 unsigned long long __builtin_addcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout);
2645 unsigned char __builtin_subcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout);
2646 unsigned short __builtin_subcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout);
2647 unsigned __builtin_subc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout);
2648 unsigned long __builtin_subcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout);
2649 unsigned long long __builtin_subcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout);
2651 Checked Arithmetic Builtins
2652 ---------------------------
2654 Clang provides a set of builtins that implement checked arithmetic for security
2655 critical applications in a manner that is fast and easily expressible in C. As
2656 an example of their usage:
2660 errorcode_t security_critical_application(...) {
2661 unsigned x, y, result;
2663 if (__builtin_mul_overflow(x, y, &result))
2664 return kErrorCodeHackers;
2666 use_multiply(result);
2670 Clang provides the following checked arithmetic builtins:
2674 bool __builtin_add_overflow (type1 x, type2 y, type3 *sum);
2675 bool __builtin_sub_overflow (type1 x, type2 y, type3 *diff);
2676 bool __builtin_mul_overflow (type1 x, type2 y, type3 *prod);
2677 bool __builtin_uadd_overflow (unsigned x, unsigned y, unsigned *sum);
2678 bool __builtin_uaddl_overflow (unsigned long x, unsigned long y, unsigned long *sum);
2679 bool __builtin_uaddll_overflow(unsigned long long x, unsigned long long y, unsigned long long *sum);
2680 bool __builtin_usub_overflow (unsigned x, unsigned y, unsigned *diff);
2681 bool __builtin_usubl_overflow (unsigned long x, unsigned long y, unsigned long *diff);
2682 bool __builtin_usubll_overflow(unsigned long long x, unsigned long long y, unsigned long long *diff);
2683 bool __builtin_umul_overflow (unsigned x, unsigned y, unsigned *prod);
2684 bool __builtin_umull_overflow (unsigned long x, unsigned long y, unsigned long *prod);
2685 bool __builtin_umulll_overflow(unsigned long long x, unsigned long long y, unsigned long long *prod);
2686 bool __builtin_sadd_overflow (int x, int y, int *sum);
2687 bool __builtin_saddl_overflow (long x, long y, long *sum);
2688 bool __builtin_saddll_overflow(long long x, long long y, long long *sum);
2689 bool __builtin_ssub_overflow (int x, int y, int *diff);
2690 bool __builtin_ssubl_overflow (long x, long y, long *diff);
2691 bool __builtin_ssubll_overflow(long long x, long long y, long long *diff);
2692 bool __builtin_smul_overflow (int x, int y, int *prod);
2693 bool __builtin_smull_overflow (long x, long y, long *prod);
2694 bool __builtin_smulll_overflow(long long x, long long y, long long *prod);
2696 Each builtin performs the specified mathematical operation on the
2697 first two arguments and stores the result in the third argument. If
2698 possible, the result will be equal to mathematically-correct result
2699 and the builtin will return 0. Otherwise, the builtin will return
2700 1 and the result will be equal to the unique value that is equivalent
2701 to the mathematically-correct result modulo two raised to the *k*
2702 power, where *k* is the number of bits in the result type. The
2703 behavior of these builtins is well-defined for all argument values.
2705 The first three builtins work generically for operands of any integer type,
2706 including boolean types. The operands need not have the same type as each
2707 other, or as the result. The other builtins may implicitly promote or
2708 convert their operands before performing the operation.
2710 Query for this feature with ``__has_builtin(__builtin_add_overflow)``, etc.
2712 Floating point builtins
2713 ---------------------------------------
2715 ``__builtin_canonicalize``
2716 --------------------------
2720 double __builtin_canonicalize(double);
2721 float __builtin_canonicalizef(float);
2722 long double__builtin_canonicalizel(long double);
2724 Returns the platform specific canonical encoding of a floating point
2725 number. This canonicalization is useful for implementing certain
2726 numeric primitives such as frexp. See `LLVM canonicalize intrinsic
2727 <https://llvm.org/docs/LangRef.html#llvm-canonicalize-intrinsic>`_ for
2728 more information on the semantics.
2733 Clang provides constant expression evaluation support for builtins forms of
2734 the following functions from the C standard library headers
2735 ``<string.h>`` and ``<wchar.h>``:
2738 * ``memcmp`` (and its deprecated BSD / POSIX alias ``bcmp``)
2750 In each case, the builtin form has the name of the C library function prefixed
2751 by ``__builtin_``. Example:
2755 void *p = __builtin_memchr("foobar", 'b', 5);
2757 In addition to the above, one further builtin is provided:
2761 char *__builtin_char_memchr(const char *haystack, int needle, size_t size);
2763 ``__builtin_char_memchr(a, b, c)`` is identical to
2764 ``(char*)__builtin_memchr(a, b, c)`` except that its use is permitted within
2765 constant expressions in C++11 onwards (where a cast from ``void*`` to ``char*``
2766 is disallowed in general).
2768 Constant evaluation support for the ``__builtin_mem*`` functions is provided
2769 only for arrays of ``char``, ``signed char``, ``unsigned char``, or ``char8_t``,
2770 despite these functions accepting an argument of type ``const void*``.
2772 Support for constant expression evaluation for the above builtins can be detected
2773 with ``__has_feature(cxx_constexpr_string_builtins)``.
2778 Clang provides constant expression evaluation support for builtin forms of the
2779 following functions from the C standard library headers
2780 ``<string.h>`` and ``<wchar.h>``:
2787 In each case, the builtin form has the name of the C library function prefixed
2790 Constant evaluation support is only provided when the source and destination
2791 are pointers to arrays with the same trivially copyable element type, and the
2792 given size is an exact multiple of the element size that is no greater than
2793 the number of elements accessible through the source and destination operands.
2795 Guaranteed inlined copy
2796 ^^^^^^^^^^^^^^^^^^^^^^^
2800 void __builtin_memcpy_inline(void *dst, const void *src, size_t size);
2803 ``__builtin_memcpy_inline`` has been designed as a building block for efficient
2804 ``memcpy`` implementations. It is identical to ``__builtin_memcpy`` but also
2805 guarantees not to call any external functions. See LLVM IR `llvm.memcpy.inline
2806 <https://llvm.org/docs/LangRef.html#llvm-memcpy-inline-intrinsic>`_ intrinsic
2807 for more information.
2809 This is useful to implement a custom version of ``memcpy``, implement a
2810 ``libc`` memcpy or work around the absence of a ``libc``.
2812 Note that the `size` argument must be a compile time constant.
2814 Note that this intrinsic cannot yet be called in a ``constexpr`` context.
2817 Atomic Min/Max builtins with memory ordering
2818 --------------------------------------------
2820 There are two atomic builtins with min/max in-memory comparison and swap.
2821 The syntax and semantics are similar to GCC-compatible __atomic_* builtins.
2823 * ``__atomic_fetch_min``
2824 * ``__atomic_fetch_max``
2826 The builtins work with signed and unsigned integers and require to specify memory ordering.
2827 The return value is the original value that was stored in memory before comparison.
2833 unsigned int val = __atomic_fetch_min(unsigned int *pi, unsigned int ui, __ATOMIC_RELAXED);
2835 The third argument is one of the memory ordering specifiers ``__ATOMIC_RELAXED``,
2836 ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``, ``__ATOMIC_RELEASE``,
2837 ``__ATOMIC_ACQ_REL``, or ``__ATOMIC_SEQ_CST`` following C++11 memory model semantics.
2839 In terms or aquire-release ordering barriers these two operations are always
2840 considered as operations with *load-store* semantics, even when the original value
2841 is not actually modified after comparison.
2843 .. _langext-__c11_atomic:
2845 __c11_atomic builtins
2846 ---------------------
2848 Clang provides a set of builtins which are intended to be used to implement
2849 C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the
2850 ``_explicit`` form of the corresponding C11 operation, and are named with a
2851 ``__c11_`` prefix. The supported operations, and the differences from
2852 the corresponding C11 operations, are:
2854 * ``__c11_atomic_init``
2855 * ``__c11_atomic_thread_fence``
2856 * ``__c11_atomic_signal_fence``
2857 * ``__c11_atomic_is_lock_free`` (The argument is the size of the
2858 ``_Atomic(...)`` object, instead of its address)
2859 * ``__c11_atomic_store``
2860 * ``__c11_atomic_load``
2861 * ``__c11_atomic_exchange``
2862 * ``__c11_atomic_compare_exchange_strong``
2863 * ``__c11_atomic_compare_exchange_weak``
2864 * ``__c11_atomic_fetch_add``
2865 * ``__c11_atomic_fetch_sub``
2866 * ``__c11_atomic_fetch_and``
2867 * ``__c11_atomic_fetch_or``
2868 * ``__c11_atomic_fetch_xor``
2869 * ``__c11_atomic_fetch_nand`` (Nand is not presented in ``<stdatomic.h>``)
2870 * ``__c11_atomic_fetch_max``
2871 * ``__c11_atomic_fetch_min``
2873 The macros ``__ATOMIC_RELAXED``, ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``,
2874 ``__ATOMIC_RELEASE``, ``__ATOMIC_ACQ_REL``, and ``__ATOMIC_SEQ_CST`` are
2875 provided, with values corresponding to the enumerators of C11's
2876 ``memory_order`` enumeration.
2878 (Note that Clang additionally provides GCC-compatible ``__atomic_*``
2879 builtins and OpenCL 2.0 ``__opencl_atomic_*`` builtins. The OpenCL 2.0
2880 atomic builtins are an explicit form of the corresponding OpenCL 2.0
2881 builtin function, and are named with a ``__opencl_`` prefix. The macros
2882 ``__OPENCL_MEMORY_SCOPE_WORK_ITEM``, ``__OPENCL_MEMORY_SCOPE_WORK_GROUP``,
2883 ``__OPENCL_MEMORY_SCOPE_DEVICE``, ``__OPENCL_MEMORY_SCOPE_ALL_SVM_DEVICES``,
2884 and ``__OPENCL_MEMORY_SCOPE_SUB_GROUP`` are provided, with values
2885 corresponding to the enumerators of OpenCL's ``memory_scope`` enumeration.)
2887 Low-level ARM exclusive memory builtins
2888 ---------------------------------------
2890 Clang provides overloaded builtins giving direct access to the three key ARM
2891 instructions for implementing atomic operations.
2895 T __builtin_arm_ldrex(const volatile T *addr);
2896 T __builtin_arm_ldaex(const volatile T *addr);
2897 int __builtin_arm_strex(T val, volatile T *addr);
2898 int __builtin_arm_stlex(T val, volatile T *addr);
2899 void __builtin_arm_clrex(void);
2901 The types ``T`` currently supported are:
2903 * Integer types with width at most 64 bits (or 128 bits on AArch64).
2904 * Floating-point types
2907 Note that the compiler does not guarantee it will not insert stores which clear
2908 the exclusive monitor in between an ``ldrex`` type operation and its paired
2909 ``strex``. In practice this is only usually a risk when the extra store is on
2910 the same cache line as the variable being modified and Clang will only insert
2911 stack stores on its own, so it is best not to use these operations on variables
2912 with automatic storage duration.
2914 Also, loads and stores may be implicit in code written between the ``ldrex`` and
2915 ``strex``. Clang will not necessarily mitigate the effects of these either, so
2916 care should be exercised.
2918 For these reasons the higher level atomic primitives should be preferred where
2921 Non-temporal load/store builtins
2922 --------------------------------
2924 Clang provides overloaded builtins allowing generation of non-temporal memory
2929 T __builtin_nontemporal_load(T *addr);
2930 void __builtin_nontemporal_store(T value, T *addr);
2932 The types ``T`` currently supported are:
2935 * Floating-point types.
2938 Note that the compiler does not guarantee that non-temporal loads or stores
2941 C++ Coroutines support builtins
2942 --------------------------------
2945 This is a work in progress. Compatibility across Clang/LLVM releases is not
2948 Clang provides experimental builtins to support C++ Coroutines as defined by
2949 https://wg21.link/P0057. The following four are intended to be used by the
2950 standard library to implement the ``std::coroutine_handle`` type.
2956 void __builtin_coro_resume(void *addr);
2957 void __builtin_coro_destroy(void *addr);
2958 bool __builtin_coro_done(void *addr);
2959 void *__builtin_coro_promise(void *addr, int alignment, bool from_promise)
2965 template <> struct coroutine_handle<void> {
2966 void resume() const { __builtin_coro_resume(ptr); }
2967 void destroy() const { __builtin_coro_destroy(ptr); }
2968 bool done() const { return __builtin_coro_done(ptr); }
2974 template <typename Promise> struct coroutine_handle : coroutine_handle<> {
2976 Promise &promise() const {
2977 return *reinterpret_cast<Promise *>(
2978 __builtin_coro_promise(ptr, alignof(Promise), /*from-promise=*/false));
2980 static coroutine_handle from_promise(Promise &promise) {
2982 p.ptr = __builtin_coro_promise(&promise, alignof(Promise),
2983 /*from-promise=*/true);
2989 Other coroutine builtins are either for internal clang use or for use during
2990 development of the coroutine feature. See `Coroutines in LLVM
2991 <https://llvm.org/docs/Coroutines.html#intrinsics>`_ for
2992 more information on their semantics. Note that builtins matching the intrinsics
2993 that take token as the first parameter (llvm.coro.begin, llvm.coro.alloc,
2994 llvm.coro.free and llvm.coro.suspend) omit the token parameter and fill it to
2995 an appropriate value during the emission.
3001 size_t __builtin_coro_size()
3002 void *__builtin_coro_frame()
3003 void *__builtin_coro_free(void *coro_frame)
3005 void *__builtin_coro_id(int align, void *promise, void *fnaddr, void *parts)
3006 bool __builtin_coro_alloc()
3007 void *__builtin_coro_begin(void *memory)
3008 void __builtin_coro_end(void *coro_frame, bool unwind)
3009 char __builtin_coro_suspend(bool final)
3010 bool __builtin_coro_param(void *original, void *copy)
3012 Note that there is no builtin matching the `llvm.coro.save` intrinsic. LLVM
3013 automatically will insert one if the first argument to `llvm.coro.suspend` is
3014 token `none`. If a user calls `__builin_suspend`, clang will insert `token none`
3015 as the first argument to the intrinsic.
3017 Source location builtins
3018 ------------------------
3020 Clang provides experimental builtins to support C++ standard library implementation
3021 of ``std::experimental::source_location`` as specified in http://wg21.link/N4600.
3022 With the exception of ``__builtin_COLUMN``, these builtins are also implemented by
3029 const char *__builtin_FILE();
3030 const char *__builtin_FUNCTION();
3031 unsigned __builtin_LINE();
3032 unsigned __builtin_COLUMN(); // Clang only
3038 void my_assert(bool pred, int line = __builtin_LINE(), // Captures line of caller
3039 const char* file = __builtin_FILE(),
3040 const char* function = __builtin_FUNCTION()) {
3042 printf("%s:%d assertion failed in function %s\n", file, line, function);
3046 struct MyAggregateType {
3048 int line = __builtin_LINE(); // captures line where aggregate initialization occurs
3050 static_assert(MyAggregateType{42}.line == __LINE__);
3052 struct MyClassType {
3053 int line = __builtin_LINE(); // captures line of the constructor used during initialization
3054 constexpr MyClassType(int) { assert(line == __LINE__); }
3059 The builtins ``__builtin_LINE``, ``__builtin_FUNCTION``, and ``__builtin_FILE`` return
3060 the values, at the "invocation point", for ``__LINE__``, ``__FUNCTION__``, and
3061 ``__FILE__`` respectively. These builtins are constant expressions.
3063 When the builtins appear as part of a default function argument the invocation
3064 point is the location of the caller. When the builtins appear as part of a
3065 default member initializer, the invocation point is the location of the
3066 constructor or aggregate initialization used to create the object. Otherwise
3067 the invocation point is the same as the location of the builtin.
3069 When the invocation point of ``__builtin_FUNCTION`` is not a function scope the
3070 empty string is returned.
3074 Clang provides builtins to support checking and adjusting alignment of
3075 pointers and integers.
3076 These builtins can be used to avoid relying on implementation-defined behavior
3077 of arithmetic on integers derived from pointers.
3078 Additionally, these builtins retain type information and, unlike bitwise
3079 arithmetic, they can perform semantic checking on the alignment value.
3085 Type __builtin_align_up(Type value, size_t alignment);
3086 Type __builtin_align_down(Type value, size_t alignment);
3087 bool __builtin_is_aligned(Type value, size_t alignment);
3094 char* global_alloc_buffer;
3095 void* my_aligned_allocator(size_t alloc_size, size_t alignment) {
3096 char* result = __builtin_align_up(global_alloc_buffer, alignment);
3097 // result now contains the value of global_alloc_buffer rounded up to the
3098 // next multiple of alignment.
3099 global_alloc_buffer = result + alloc_size;
3103 void* get_start_of_page(void* ptr) {
3104 return __builtin_align_down(ptr, PAGE_SIZE);
3107 void example(char* buffer) {
3108 if (__builtin_is_aligned(buffer, 64)) {
3109 do_fast_aligned_copy(buffer);
3111 do_unaligned_copy(buffer);
3115 // In addition to pointers, the builtins can also be used on integer types
3116 // and are evaluatable inside constant expressions.
3117 static_assert(__builtin_align_up(123, 64) == 128, "");
3118 static_assert(__builtin_align_down(123u, 64) == 64u, "");
3119 static_assert(!__builtin_is_aligned(123, 64), "");
3124 The builtins ``__builtin_align_up``, ``__builtin_align_down``, return their
3125 first argument aligned up/down to the next multiple of the second argument.
3126 If the value is already sufficiently aligned, it is returned unchanged.
3127 The builtin ``__builtin_is_aligned`` returns whether the first argument is
3128 aligned to a multiple of the second argument.
3129 All of these builtins expect the alignment to be expressed as a number of bytes.
3131 These builtins can be used for all integer types as well as (non-function)
3132 pointer types. For pointer types, these builtins operate in terms of the integer
3133 address of the pointer and return a new pointer of the same type (including
3134 qualifiers such as ``const``) with an adjusted address.
3135 When aligning pointers up or down, the resulting value must be within the same
3136 underlying allocation or one past the end (see C17 6.5.6p8, C++ [expr.add]).
3137 This means that arbitrary integer values stored in pointer-type variables must
3138 not be passed to these builtins. For those use cases, the builtins can still be
3139 used, but the operation must be performed on the pointer cast to ``uintptr_t``.
3141 If Clang can determine that the alignment is not a power of two at compile time,
3142 it will result in a compilation failure. If the alignment argument is not a
3143 power of two at run time, the behavior of these builtins is undefined.
3145 Non-standard C++11 Attributes
3146 =============================
3148 Clang's non-standard C++11 attributes live in the ``clang`` attribute
3151 Clang supports GCC's ``gnu`` attribute namespace. All GCC attributes which
3152 are accepted with the ``__attribute__((foo))`` syntax are also accepted as
3153 ``[[gnu::foo]]``. This only extends to attributes which are specified by GCC
3154 (see the list of `GCC function attributes
3155 <https://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_, `GCC variable
3156 attributes <https://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html>`_, and
3157 `GCC type attributes
3158 <https://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html>`_). As with the GCC
3159 implementation, these attributes must appertain to the *declarator-id* in a
3160 declaration, which means they must go either at the start of the declaration or
3161 immediately after the name being declared.
3163 For example, this applies the GNU ``unused`` attribute to ``a`` and ``f``, and
3164 also applies the GNU ``noreturn`` attribute to ``f``.
3168 [[gnu::unused]] int a, f [[gnu::noreturn]] ();
3170 Target-Specific Extensions
3171 ==========================
3173 Clang supports some language features conditionally on some targets.
3175 ARM/AArch64 Language Extensions
3176 -------------------------------
3178 Memory Barrier Intrinsics
3179 ^^^^^^^^^^^^^^^^^^^^^^^^^
3180 Clang implements the ``__dmb``, ``__dsb`` and ``__isb`` intrinsics as defined
3181 in the `ARM C Language Extensions Release 2.0
3182 <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_.
3183 Note that these intrinsics are implemented as motion barriers that block
3184 reordering of memory accesses and side effect instructions. Other instructions
3185 like simple arithmetic may be reordered around the intrinsic. If you expect to
3186 have no reordering at all, use inline assembly instead.
3188 X86/X86-64 Language Extensions
3189 ------------------------------
3191 The X86 backend has these language extensions:
3193 Memory references to specified segments
3194 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3196 Annotating a pointer with address space #256 causes it to be code generated
3197 relative to the X86 GS segment register, address space #257 causes it to be
3198 relative to the X86 FS segment, and address space #258 causes it to be
3199 relative to the X86 SS segment. Note that this is a very very low-level
3200 feature that should only be used if you know what you're doing (for example in
3207 #define GS_RELATIVE __attribute__((address_space(256)))
3208 int foo(int GS_RELATIVE *P) {
3212 Which compiles to (on X86-32):
3218 movl %gs:(%eax), %eax
3221 You can also use the GCC compatibility macros ``__seg_fs`` and ``__seg_gs`` for
3222 the same purpose. The preprocessor symbols ``__SEG_FS`` and ``__SEG_GS``
3223 indicate their support.
3225 PowerPC Language Extensions
3226 ---------------------------
3228 Set the Floating Point Rounding Mode
3229 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3230 PowerPC64/PowerPC64le supports the builtin function ``__builtin_setrnd`` to set
3231 the floating point rounding mode. This function will use the least significant
3232 two bits of integer argument to set the floating point rounding mode.
3236 double __builtin_setrnd(int mode);
3238 The effective values for mode are:
3240 - 0 - round to nearest
3242 - 2 - round to +infinity
3243 - 3 - round to -infinity
3245 Note that the mode argument will modulo 4, so if the integer argument is greater
3246 than 3, it will only use the least significant two bits of the mode.
3247 Namely, ``__builtin_setrnd(102))`` is equal to ``__builtin_setrnd(2)``.
3249 PowerPC cache builtins
3250 ^^^^^^^^^^^^^^^^^^^^^^
3252 The PowerPC architecture specifies instructions implementing cache operations.
3253 Clang provides builtins that give direct programmer access to these cache
3256 Currently the following builtins are implemented in clang:
3258 ``__builtin_dcbf`` copies the contents of a modified block from the data cache
3259 to main memory and flushes the copy from the data cache.
3265 void __dcbf(const void* addr); /* Data Cache Block Flush */
3272 __builtin_dcbf (&a);
3274 Extensions for Static Analysis
3275 ==============================
3277 Clang supports additional attributes that are useful for documenting program
3278 invariants and rules for static analysis tools, such as the `Clang Static
3279 Analyzer <https://clang-analyzer.llvm.org/>`_. These attributes are documented
3280 in the analyzer's `list of source-level annotations
3281 <https://clang-analyzer.llvm.org/annotations.html>`_.
3284 Extensions for Dynamic Analysis
3285 ===============================
3287 Use ``__has_feature(address_sanitizer)`` to check if the code is being built
3288 with :doc:`AddressSanitizer`.
3290 Use ``__has_feature(thread_sanitizer)`` to check if the code is being built
3291 with :doc:`ThreadSanitizer`.
3293 Use ``__has_feature(memory_sanitizer)`` to check if the code is being built
3294 with :doc:`MemorySanitizer`.
3296 Use ``__has_feature(safe_stack)`` to check if the code is being built
3297 with :doc:`SafeStack`.
3300 Extensions for selectively disabling optimization
3301 =================================================
3303 Clang provides a mechanism for selectively disabling optimizations in functions
3306 To disable optimizations in a single function definition, the GNU-style or C++11
3307 non-standard attribute ``optnone`` can be used.
3311 // The following functions will not be optimized.
3312 // GNU-style attribute
3313 __attribute__((optnone)) int foo() {
3317 [[clang::optnone]] int bar() {
3321 To facilitate disabling optimization for a range of function definitions, a
3322 range-based pragma is provided. Its syntax is ``#pragma clang optimize``
3323 followed by ``off`` or ``on``.
3325 All function definitions in the region between an ``off`` and the following
3326 ``on`` will be decorated with the ``optnone`` attribute unless doing so would
3327 conflict with explicit attributes already present on the function (e.g. the
3328 ones that control inlining).
3332 #pragma clang optimize off
3333 // This function will be decorated with optnone.
3338 // optnone conflicts with always_inline, so bar() will not be decorated.
3339 __attribute__((always_inline)) int bar() {
3342 #pragma clang optimize on
3344 If no ``on`` is found to close an ``off`` region, the end of the region is the
3345 end of the compilation unit.
3347 Note that a stray ``#pragma clang optimize on`` does not selectively enable
3348 additional optimizations when compiling at low optimization levels. This feature
3349 can only be used to selectively disable optimizations.
3351 The pragma has an effect on functions only at the point of their definition; for
3352 function templates, this means that the state of the pragma at the point of an
3353 instantiation is not necessarily relevant. Consider the following example:
3357 template<typename T> T twice(T t) {
3361 #pragma clang optimize off
3362 template<typename T> T thrice(T t) {
3366 int container(int a, int b) {
3367 return twice(a) + thrice(b);
3369 #pragma clang optimize on
3371 In this example, the definition of the template function ``twice`` is outside
3372 the pragma region, whereas the definition of ``thrice`` is inside the region.
3373 The ``container`` function is also in the region and will not be optimized, but
3374 it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of
3375 these two instantiations, ``twice`` will be optimized (because its definition
3376 was outside the region) and ``thrice`` will not be optimized.
3378 Extensions for loop hint optimizations
3379 ======================================
3381 The ``#pragma clang loop`` directive is used to specify hints for optimizing the
3382 subsequent for, while, do-while, or c++11 range-based for loop. The directive
3383 provides options for vectorization, interleaving, predication, unrolling and
3384 distribution. Loop hints can be specified before any loop and will be ignored if
3385 the optimization is not safe to apply.
3387 There are loop hints that control transformations (e.g. vectorization, loop
3388 unrolling) and there are loop hints that set transformation options (e.g.
3389 ``vectorize_width``, ``unroll_count``). Pragmas setting transformation options
3390 imply the transformation is enabled, as if it was enabled via the corresponding
3391 transformation pragma (e.g. ``vectorize(enable)``). If the transformation is
3392 disabled (e.g. ``vectorize(disable)``), that takes precedence over
3393 transformations option pragmas implying that transformation.
3395 Vectorization, Interleaving, and Predication
3396 --------------------------------------------
3398 A vectorized loop performs multiple iterations of the original loop
3399 in parallel using vector instructions. The instruction set of the target
3400 processor determines which vector instructions are available and their vector
3401 widths. This restricts the types of loops that can be vectorized. The vectorizer
3402 automatically determines if the loop is safe and profitable to vectorize. A
3403 vector instruction cost model is used to select the vector width.
3405 Interleaving multiple loop iterations allows modern processors to further
3406 improve instruction-level parallelism (ILP) using advanced hardware features,
3407 such as multiple execution units and out-of-order execution. The vectorizer uses
3408 a cost model that depends on the register pressure and generated code size to
3409 select the interleaving count.
3411 Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled
3412 by ``interleave(enable)``. This is useful when compiling with ``-Os`` to
3413 manually enable vectorization or interleaving.
3417 #pragma clang loop vectorize(enable)
3418 #pragma clang loop interleave(enable)
3423 The vector width is specified by
3424 ``vectorize_width(_value_[, fixed|scalable])``, where _value_ is a positive
3425 integer and the type of vectorization can be specified with an optional
3426 second parameter. The default for the second parameter is 'fixed' and
3427 refers to fixed width vectorization, whereas 'scalable' indicates the
3428 compiler should use scalable vectors instead. Another use of vectorize_width
3429 is ``vectorize_width(fixed|scalable)`` where the user can hint at the type
3430 of vectorization to use without specifying the exact width. In both variants
3431 of the pragma the vectorizer may decide to fall back on fixed width
3432 vectorization if the target does not support scalable vectors.
3434 The interleave count is specified by ``interleave_count(_value_)``, where
3435 _value_ is a positive integer. This is useful for specifying the optimal
3436 width/count of the set of target architectures supported by your application.
3440 #pragma clang loop vectorize_width(2)
3441 #pragma clang loop interleave_count(2)
3446 Specifying a width/count of 1 disables the optimization, and is equivalent to
3447 ``vectorize(disable)`` or ``interleave(disable)``.
3449 Vector predication is enabled by ``vectorize_predicate(enable)``, for example:
3453 #pragma clang loop vectorize(enable)
3454 #pragma clang loop vectorize_predicate(enable)
3459 This predicates (masks) all instructions in the loop, which allows the scalar
3460 remainder loop (the tail) to be folded into the main vectorized loop. This
3461 might be more efficient when vector predication is efficiently supported by the
3467 Unrolling a loop reduces the loop control overhead and exposes more
3468 opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling
3469 eliminates the loop and replaces it with an enumerated sequence of loop
3470 iterations. Full unrolling is only possible if the loop trip count is known at
3471 compile time. Partial unrolling replicates the loop body within the loop and
3472 reduces the trip count.
3474 If ``unroll(enable)`` is specified the unroller will attempt to fully unroll the
3475 loop if the trip count is known at compile time. If the fully unrolled code size
3476 is greater than an internal limit the loop will be partially unrolled up to this
3477 limit. If the trip count is not known at compile time the loop will be partially
3478 unrolled with a heuristically chosen unroll factor.
3482 #pragma clang loop unroll(enable)
3487 If ``unroll(full)`` is specified the unroller will attempt to fully unroll the
3488 loop if the trip count is known at compile time identically to
3489 ``unroll(enable)``. However, with ``unroll(full)`` the loop will not be unrolled
3490 if the loop count is not known at compile time.
3494 #pragma clang loop unroll(full)
3499 The unroll count can be specified explicitly with ``unroll_count(_value_)`` where
3500 _value_ is a positive integer. If this value is greater than the trip count the
3501 loop will be fully unrolled. Otherwise the loop is partially unrolled subject
3502 to the same code size limit as with ``unroll(enable)``.
3506 #pragma clang loop unroll_count(8)
3511 Unrolling of a loop can be prevented by specifying ``unroll(disable)``.
3513 Loop unroll parameters can be controlled by options
3514 `-mllvm -unroll-count=n` and `-mllvm -pragma-unroll-threshold=n`.
3519 Loop Distribution allows splitting a loop into multiple loops. This is
3520 beneficial for example when the entire loop cannot be vectorized but some of the
3521 resulting loops can.
3523 If ``distribute(enable))`` is specified and the loop has memory dependencies
3524 that inhibit vectorization, the compiler will attempt to isolate the offending
3525 operations into a new loop. This optimization is not enabled by default, only
3526 loops marked with the pragma are considered.
3530 #pragma clang loop distribute(enable)
3531 for (i = 0; i < N; ++i) {
3532 S1: A[i + 1] = A[i] + B[i];
3533 S2: C[i] = D[i] * E[i];
3536 This loop will be split into two loops between statements S1 and S2. The
3537 second loop containing S2 will be vectorized.
3539 Loop Distribution is currently not enabled by default in the optimizer because
3540 it can hurt performance in some cases. For example, instruction-level
3541 parallelism could be reduced by sequentializing the execution of the
3542 statements S1 and S2 above.
3544 If Loop Distribution is turned on globally with
3545 ``-mllvm -enable-loop-distribution``, specifying ``distribute(disable)`` can
3546 be used the disable it on a per-loop basis.
3548 Additional Information
3549 ----------------------
3551 For convenience multiple loop hints can be specified on a single line.
3555 #pragma clang loop vectorize_width(4) interleave_count(8)
3560 If an optimization cannot be applied any hints that apply to it will be ignored.
3561 For example, the hint ``vectorize_width(4)`` is ignored if the loop is not
3562 proven safe to vectorize. To identify and diagnose optimization issues use
3563 `-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the
3564 user guide for details.
3566 Extensions to specify floating-point flags
3567 ====================================================
3569 The ``#pragma clang fp`` pragma allows floating-point options to be specified
3570 for a section of the source code. This pragma can only appear at file scope or
3571 at the start of a compound statement (excluding comments). When using within a
3572 compound statement, the pragma is active within the scope of the compound
3575 Currently, the following settings can be controlled with this pragma:
3577 ``#pragma clang fp reassociate`` allows control over the reassociation
3578 of floating point expressions. When enabled, this pragma allows the expression
3579 ``x + (y + z)`` to be reassociated as ``(x + y) + z``.
3580 Reassociation can also occur across multiple statements.
3581 This pragma can be used to disable reassociation when it is otherwise
3582 enabled for the translation unit with the ``-fassociative-math`` flag.
3583 The pragma can take two values: ``on`` and ``off``.
3587 float f(float x, float y, float z)
3589 // Enable floating point reassociation across statements
3590 #pragma clang fp reassociate(on)
3596 ``#pragma clang fp contract`` specifies whether the compiler should
3597 contract a multiply and an addition (or subtraction) into a fused FMA
3598 operation when supported by the target.
3600 The pragma can take three values: ``on``, ``fast`` and ``off``. The ``on``
3601 option is identical to using ``#pragma STDC FP_CONTRACT(ON)`` and it allows
3602 fusion as specified the language standard. The ``fast`` option allows fusion
3603 in cases when the language standard does not make this possible (e.g. across
3609 #pragma clang fp contract(fast)
3615 The pragma can also be used with ``off`` which turns FP contraction off for a
3616 section of the code. This can be useful when fast contraction is otherwise
3617 enabled for the translation unit with the ``-ffp-contract=fast-honor-pragmas`` flag.
3618 Note that ``-ffp-contract=fast`` will override pragmas to fuse multiply and
3619 addition across statements regardless of any controlling pragmas.
3621 ``#pragma clang fp exceptions`` specifies floating point exception behavior. It
3622 may take one the the values: ``ignore``, ``maytrap`` or ``strict``. Meaning of
3623 these values is same as for `constrained floating point intrinsics <http://llvm.org/docs/LangRef.html#constrained-floating-point-intrinsics>`_.
3628 // Preserve floating point exceptions
3629 #pragma clang fp exceptions(strict)
3631 if (fetestexcept(FE_OVERFLOW))
3635 A ``#pragma clang fp`` pragma may contain any number of options:
3639 void func(float *dest, float a, float b) {
3640 #pragma clang fp exceptions(maytrap) contract(fast) reassociate(on)
3645 The ``#pragma float_control`` pragma allows precise floating-point
3646 semantics and floating-point exception behavior to be specified
3647 for a section of the source code. This pragma can only appear at file or
3648 namespace scope, within a language linkage specification or at the start of a
3649 compound statement (excluding comments). When used within a compound statement,
3650 the pragma is active within the scope of the compound statement. This pragma
3651 is modeled after a Microsoft pragma with the same spelling and syntax. For
3652 pragmas specified at file or namespace scope, or within a language linkage
3653 specification, a stack is supported so that the ``pragma float_control``
3654 settings can be pushed or popped.
3656 When ``pragma float_control(precise, on)`` is enabled, the section of code
3657 governed by the pragma uses precise floating point semantics, effectively
3658 ``-ffast-math`` is disabled and ``-ffp-contract=on``
3659 (fused multiply add) is enabled.
3661 When ``pragma float_control(except, on)`` is enabled, the section of code
3662 governed by the pragma behaves as though the command-line option
3663 ``-ffp-exception-behavior=strict`` is enabled,
3664 when ``pragma float_control(except, off)`` is enabled, the section of code
3665 governed by the pragma behaves as though the command-line option
3666 ``-ffp-exception-behavior=ignore`` is enabled.
3668 The full syntax this pragma supports is
3669 ``float_control(except|precise, on|off [, push])`` and
3670 ``float_control(push|pop)``.
3671 The ``push`` and ``pop`` forms, including using ``push`` as the optional
3672 third argument, can only occur at file scope.
3677 // This block will be compiled with -fno-fast-math and -ffp-contract=on
3678 #pragma float_control(precise, on)
3679 a = b[i] * c[i] + e;
3682 Specifying an attribute for multiple declarations (#pragma clang attribute)
3683 ===========================================================================
3685 The ``#pragma clang attribute`` directive can be used to apply an attribute to
3686 multiple declarations. The ``#pragma clang attribute push`` variation of the
3687 directive pushes a new "scope" of ``#pragma clang attribute`` that attributes
3688 can be added to. The ``#pragma clang attribute (...)`` variation adds an
3689 attribute to that scope, and the ``#pragma clang attribute pop`` variation pops
3690 the scope. You can also use ``#pragma clang attribute push (...)``, which is a
3691 shorthand for when you want to add one attribute to a new scope. Multiple push
3692 directives can be nested inside each other.
3694 The attributes that are used in the ``#pragma clang attribute`` directives
3695 can be written using the GNU-style syntax:
3699 #pragma clang attribute push (__attribute__((annotate("custom"))), apply_to = function)
3701 void function(); // The function now has the annotate("custom") attribute
3703 #pragma clang attribute pop
3705 The attributes can also be written using the C++11 style syntax:
3709 #pragma clang attribute push ([[noreturn]], apply_to = function)
3711 void function(); // The function now has the [[noreturn]] attribute
3713 #pragma clang attribute pop
3715 The ``__declspec`` style syntax is also supported:
3719 #pragma clang attribute push (__declspec(dllexport), apply_to = function)
3721 void function(); // The function now has the __declspec(dllexport) attribute
3723 #pragma clang attribute pop
3725 A single push directive accepts only one attribute regardless of the syntax
3728 Because multiple push directives can be nested, if you're writing a macro that
3729 expands to ``_Pragma("clang attribute")`` it's good hygiene (though not
3730 required) to add a namespace to your push/pop directives. A pop directive with a
3731 namespace will pop the innermost push that has that same namespace. This will
3732 ensure that another macro's ``pop`` won't inadvertently pop your attribute. Note
3733 that an ``pop`` without a namespace will pop the innermost ``push`` without a
3734 namespace. ``push``es with a namespace can only be popped by ``pop`` with the
3735 same namespace. For instance:
3739 #define ASSUME_NORETURN_BEGIN _Pragma("clang attribute AssumeNoreturn.push ([[noreturn]], apply_to = function)")
3740 #define ASSUME_NORETURN_END _Pragma("clang attribute AssumeNoreturn.pop")
3742 #define ASSUME_UNAVAILABLE_BEGIN _Pragma("clang attribute Unavailable.push (__attribute__((unavailable)), apply_to=function)")
3743 #define ASSUME_UNAVAILABLE_END _Pragma("clang attribute Unavailable.pop")
3746 ASSUME_NORETURN_BEGIN
3747 ASSUME_UNAVAILABLE_BEGIN
3748 void function(); // function has [[noreturn]] and __attribute__((unavailable))
3750 void other_function(); // function has __attribute__((unavailable))
3751 ASSUME_UNAVAILABLE_END
3753 Without the namespaces on the macros, ``other_function`` will be annotated with
3754 ``[[noreturn]]`` instead of ``__attribute__((unavailable))``. This may seem like
3755 a contrived example, but its very possible for this kind of situation to appear
3756 in real code if the pragmas are spread out across a large file. You can test if
3757 your version of clang supports namespaces on ``#pragma clang attribute`` with
3758 ``__has_extension(pragma_clang_attribute_namespaces)``.
3763 The set of declarations that receive a single attribute from the attribute stack
3764 depends on the subject match rules that were specified in the pragma. Subject
3765 match rules are specified after the attribute. The compiler expects an
3766 identifier that corresponds to the subject set specifier. The ``apply_to``
3767 specifier is currently the only supported subject set specifier. It allows you
3768 to specify match rules that form a subset of the attribute's allowed subject
3769 set, i.e. the compiler doesn't require all of the attribute's subjects. For
3770 example, an attribute like ``[[nodiscard]]`` whose subject set includes
3771 ``enum``, ``record`` and ``hasType(functionType)``, requires the presence of at
3772 least one of these rules after ``apply_to``:
3776 #pragma clang attribute push([[nodiscard]], apply_to = enum)
3778 enum Enum1 { A1, B1 }; // The enum will receive [[nodiscard]]
3780 struct Record1 { }; // The struct will *not* receive [[nodiscard]]
3782 #pragma clang attribute pop
3784 #pragma clang attribute push([[nodiscard]], apply_to = any(record, enum))
3786 enum Enum2 { A2, B2 }; // The enum will receive [[nodiscard]]
3788 struct Record2 { }; // The struct *will* receive [[nodiscard]]
3790 #pragma clang attribute pop
3792 // This is an error, since [[nodiscard]] can't be applied to namespaces:
3793 #pragma clang attribute push([[nodiscard]], apply_to = any(record, namespace))
3795 #pragma clang attribute pop
3797 Multiple match rules can be specified using the ``any`` match rule, as shown
3798 in the example above. The ``any`` rule applies attributes to all declarations
3799 that are matched by at least one of the rules in the ``any``. It doesn't nest
3800 and can't be used inside the other match rules. Redundant match rules or rules
3801 that conflict with one another should not be used inside of ``any``.
3803 Clang supports the following match rules:
3805 - ``function``: Can be used to apply attributes to functions. This includes C++
3806 member functions, static functions, operators, and constructors/destructors.
3808 - ``function(is_member)``: Can be used to apply attributes to C++ member
3809 functions. This includes members like static functions, operators, and
3810 constructors/destructors.
3812 - ``hasType(functionType)``: Can be used to apply attributes to functions, C++
3813 member functions, and variables/fields whose type is a function pointer. It
3814 does not apply attributes to Objective-C methods or blocks.
3816 - ``type_alias``: Can be used to apply attributes to ``typedef`` declarations
3817 and C++11 type aliases.
3819 - ``record``: Can be used to apply attributes to ``struct``, ``class``, and
3820 ``union`` declarations.
3822 - ``record(unless(is_union))``: Can be used to apply attributes only to
3823 ``struct`` and ``class`` declarations.
3825 - ``enum``: Can be be used to apply attributes to enumeration declarations.
3827 - ``enum_constant``: Can be used to apply attributes to enumerators.
3829 - ``variable``: Can be used to apply attributes to variables, including
3830 local variables, parameters, global variables, and static member variables.
3831 It does not apply attributes to instance member variables or Objective-C
3834 - ``variable(is_thread_local)``: Can be used to apply attributes to thread-local
3837 - ``variable(is_global)``: Can be used to apply attributes to global variables
3840 - ``variable(is_local)``: Can be used to apply attributes to local variables
3843 - ``variable(is_parameter)``: Can be used to apply attributes to parameters
3846 - ``variable(unless(is_parameter))``: Can be used to apply attributes to all
3847 the variables that are not parameters.
3849 - ``field``: Can be used to apply attributes to non-static member variables
3850 in a record. This includes Objective-C ivars.
3852 - ``namespace``: Can be used to apply attributes to ``namespace`` declarations.
3854 - ``objc_interface``: Can be used to apply attributes to ``@interface``
3857 - ``objc_protocol``: Can be used to apply attributes to ``@protocol``
3860 - ``objc_category``: Can be used to apply attributes to category declarations,
3861 including class extensions.
3863 - ``objc_method``: Can be used to apply attributes to Objective-C methods,
3864 including instance and class methods. Implicit methods like implicit property
3865 getters and setters do not receive the attribute.
3867 - ``objc_method(is_instance)``: Can be used to apply attributes to Objective-C
3870 - ``objc_property``: Can be used to apply attributes to ``@property``
3873 - ``block``: Can be used to apply attributes to block declarations. This does
3874 not include variables/fields of block pointer type.
3876 The use of ``unless`` in match rules is currently restricted to a strict set of
3877 sub-rules that are used by the supported attributes. That means that even though
3878 ``variable(unless(is_parameter))`` is a valid match rule,
3879 ``variable(unless(is_thread_local))`` is not.
3881 Supported Attributes
3882 --------------------
3884 Not all attributes can be used with the ``#pragma clang attribute`` directive.
3885 Notably, statement attributes like ``[[fallthrough]]`` or type attributes
3886 like ``address_space`` aren't supported by this directive. You can determine
3887 whether or not an attribute is supported by the pragma by referring to the
3888 :doc:`individual documentation for that attribute <AttributeReference>`.
3890 The attributes are applied to all matching declarations individually, even when
3891 the attribute is semantically incorrect. The attributes that aren't applied to
3892 any declaration are not verified semantically.
3894 Specifying section names for global objects (#pragma clang section)
3895 ===================================================================
3897 The ``#pragma clang section`` directive provides a means to assign section-names
3898 to global variables, functions and static variables.
3900 The section names can be specified as:
3904 #pragma clang section bss="myBSS" data="myData" rodata="myRodata" relro="myRelro" text="myText"
3906 The section names can be reverted back to default name by supplying an empty
3907 string to the section kind, for example:
3911 #pragma clang section bss="" data="" text="" rodata="" relro=""
3913 The ``#pragma clang section`` directive obeys the following rules:
3915 * The pragma applies to all global variable, statics and function declarations
3916 from the pragma to the end of the translation unit.
3918 * The pragma clang section is enabled automatically, without need of any flags.
3920 * This feature is only defined to work sensibly for ELF targets.
3922 * If section name is specified through _attribute_((section("myname"))), then
3923 the attribute name gains precedence.
3925 * Global variables that are initialized to zero will be placed in the named
3926 bss section, if one is present.
3928 * The ``#pragma clang section`` directive does not does try to infer section-kind
3929 from the name. For example, naming a section "``.bss.mySec``" does NOT mean
3930 it will be a bss section name.
3932 * The decision about which section-kind applies to each global is taken in the back-end.
3933 Once the section-kind is known, appropriate section name, as specified by the user using
3934 ``#pragma clang section`` directive, is applied to that global.
3936 Specifying Linker Options on ELF Targets
3937 ========================================
3939 The ``#pragma comment(lib, ...)`` directive is supported on all ELF targets.
3940 The second parameter is the library name (without the traditional Unix prefix of
3941 ``lib``). This allows you to provide an implicit link of dependent libraries.
3943 Evaluating Object Size Dynamically
3944 ==================================
3946 Clang supports the builtin ``__builtin_dynamic_object_size``, the semantics are
3947 the same as GCC's ``__builtin_object_size`` (which Clang also supports), but
3948 ``__builtin_dynamic_object_size`` can evaluate the object's size at runtime.
3949 ``__builtin_dynamic_object_size`` is meant to be used as a drop-in replacement
3950 for ``__builtin_object_size`` in libraries that support it.
3952 For instance, here is a program that ``__builtin_dynamic_object_size`` will make
3957 void copy_into_buffer(size_t size) {
3958 char* buffer = malloc(size);
3959 strlcpy(buffer, "some string", strlen("some string"));
3960 // Previous line preprocesses to:
3961 // __builtin___strlcpy_chk(buffer, "some string", strlen("some string"), __builtin_object_size(buffer, 0))
3964 Since the size of ``buffer`` can't be known at compile time, Clang will fold
3965 ``__builtin_object_size(buffer, 0)`` into ``-1``. However, if this was written
3966 as ``__builtin_dynamic_object_size(buffer, 0)``, Clang will fold it into
3967 ``size``, providing some extra runtime safety.
3972 Clang supports the pragma ``#pragma clang deprecated``, which can be used to
3973 provide deprecation warnings for macro uses. For example:
3977 #define MIN(x, y) x < y ? x : y
3978 #pragma clang deprecated(MIN, "use std::min instead")
3980 void min(int a, int b) {
3981 return MIN(a, b); // warning: MIN is deprecated: use std::min instead
3984 ``#pragma clang deprecated`` should be preferred for this purpose over
3985 ``#pragma GCC warning`` because the warning can be controlled with
3988 Restricted Expansion Macros
3989 ===========================
3991 Clang supports the pragma ``#pragma clang restrict_expansion``, which can be
3992 used restrict macro expansion in headers. This can be valuable when providing
3993 headers with ABI stability requirements. Any expansion of the annotated macro
3994 processed by the preprocessor after the ``#pragma`` annotation will log a
3995 warning. Redefining the macro or undefining the macro will not be diagnosed, nor
3996 will expansion of the macro within the main source file. For example:
4000 #define TARGET_ARM 1
4001 #pragma clang restrict_expansion(TARGET_ARM, "<reason>")
4005 #if TARGET_ARM // warning: TARGET_ARM is marked unsafe in headers: <reason>
4014 #if TARGET_ARM // No warning in main source file
4020 This warning is controlled by ``-Wpedantic-macros``.
4025 Clang supports the pragma ``#pragma clang final``, which can be used to
4026 mark macros as final, meaning they cannot be undef'd or re-defined. For example:
4030 #define FINAL_MACRO 1
4031 #pragma clang final(FINAL_MACRO)
4033 #define FINAL_MACRO // warning: FINAL_MACRO is marked final and should not be redefined
4034 #undef FINAL_MACRO // warning: FINAL_MACRO is marked final and should not be undefined
4036 This is useful for enforcing system-provided macros that should not be altered
4037 in user headers or code. This is controlled by ``-Wpedantic-macros``. Final
4038 macros will always warn on redefinition, including situations with identical
4039 bodies and in system headers.
4044 Clang supports an extension for source line control, which takes the
4045 form of a preprocessor directive starting with an unsigned integral
4046 constant. In addition to the standard ``#line`` directive, this form
4047 allows control of an include stack and header file type, which is used
4048 in issuing diagnostics. These lines are emitted in preprocessed
4053 # <line:number> <filename:string> <header-type:numbers>
4055 The filename is optional, and if unspecified indicates no change in
4056 source filename. The header-type is an optional, whitespace-delimited,
4057 sequence of magic numbers as follows.
4059 * ``1:`` Push the current source file name onto the include stack and
4062 * ``2``: Pop the include stack and return to the specified file. If
4063 the filename is ``""``, the name popped from the include stack is
4064 used. Otherwise there is no requirement that the specified filename
4065 matches the current source when originally pushed.
4067 * ``3``: Enter a system-header region. System headers often contain
4068 implementation-specific source that would normally emit a diagnostic.
4070 * ``4``: Enter an implicit ``extern "C"`` region. This is not required on
4071 modern systems where system headers are C++-aware.
4073 At most a single ``1`` or ``2`` can be present, and values must be in
4080 # 57 // Advance (or return) to line 57 of the current source file
4081 # 57 "frob" // Set to line 57 of "frob"
4082 # 1 "foo.h" 1 // Enter "foo.h" at line 1
4083 # 59 "main.c" 2 // Leave current include and return to "main.c"
4084 # 1 "/usr/include/stdio.h" 1 3 // Enter a system header
4085 # 60 "" 2 // return to "main.c"
4086 # 1 "/usr/ancient/header.h" 1 4 // Enter an implicit extern "C" header
4088 Extended Integer Types
4089 ======================
4091 Clang supports a set of extended integer types under the syntax ``_ExtInt(N)``
4092 where ``N`` is an integer that specifies the number of bits that are used to represent
4093 the type, including the sign bit. The keyword ``_ExtInt`` is a type specifier, thus
4094 it can be used in any place a type can, including as a non-type-template-parameter,
4095 as the type of a bitfield, and as the underlying type of an enumeration.
4097 An extended integer can be declared either signed, or unsigned by using the
4098 ``signed``/``unsigned`` keywords. If no sign specifier is used or if the ``signed``
4099 keyword is used, the extended integer type is a signed integer and can represent
4102 The ``N`` expression is an integer constant expression, which specifies the number
4103 of bits used to represent the type, following normal integer representations for
4104 both signed and unsigned types. Both a signed and unsigned extended integer of the
4105 same ``N`` value will have the same number of bits in its representation. Many
4106 architectures don't have a way of representing non power-of-2 integers, so these
4107 architectures emulate these types using larger integers. In these cases, they are
4108 expected to follow the 'as-if' rule and do math 'as-if' they were done at the
4109 specified number of bits.
4111 In order to be consistent with the C language specification, and make the extended
4112 integer types useful for their intended purpose, extended integers follow the C
4113 standard integer conversion ranks. An extended integer type has a greater rank than
4114 any integer type with less precision. However, they have lower rank than any
4115 of the built in or other integer types (such as __int128). Usual arithmetic conversions
4116 also work the same, where the smaller ranked integer is converted to the larger.
4118 The one exception to the C rules for integers for these types is Integer Promotion.
4119 Unary +, -, and ~ operators typically will promote operands to ``int``. Doing these
4120 promotions would inflate the size of required hardware on some platforms, so extended
4121 integer types aren't subject to the integer promotion rules in these cases.
4123 In languages (such as OpenCL) that define shift by-out-of-range behavior as a mask,
4124 non-power-of-two versions of these types use an unsigned remainder operation to constrain
4125 the value to the proper range, preventing undefined behavior.
4127 Extended integer types are aligned to the next greatest power-of-2 up to 64 bits.
4128 The size of these types for the purposes of layout and ``sizeof`` are the number of
4129 bits aligned to this calculated alignment. This permits the use of these types in
4130 allocated arrays using common ``sizeof(Array)/sizeof(ElementType)`` pattern.
4132 Extended integer types work with the C _Atomic type modifier, however only precisions
4133 that are powers-of-2 greater than 8 bit are accepted.
4135 Extended integer types align with existing calling conventions. They have the same size
4136 and alignment as the smallest basic type that can contain them. Types that are larger
4137 than 64 bits are handled in the same way as _int128 is handled; they are conceptually
4138 treated as struct of register size chunks. They number of chunks are the smallest
4139 number that can contain the types which does not necessarily mean a power-of-2 size.
4141 Intrinsics Support within Constant Expressions
4142 ==============================================
4144 The following builtin intrinsics can be used in constant expressions:
4146 * ``__builtin_bitreverse8``
4147 * ``__builtin_bitreverse16``
4148 * ``__builtin_bitreverse32``
4149 * ``__builtin_bitreverse64``
4150 * ``__builtin_bswap16``
4151 * ``__builtin_bswap32``
4152 * ``__builtin_bswap64``
4153 * ``__builtin_clrsb``
4154 * ``__builtin_clrsbl``
4155 * ``__builtin_clrsbll``
4157 * ``__builtin_clzl``
4158 * ``__builtin_clzll``
4159 * ``__builtin_clzs``
4161 * ``__builtin_ctzl``
4162 * ``__builtin_ctzll``
4163 * ``__builtin_ctzs``
4165 * ``__builtin_ffsl``
4166 * ``__builtin_ffsll``
4167 * ``__builtin_fpclassify``
4169 * ``__builtin_isinf``
4170 * ``__builtin_isinf_sign``
4171 * ``__builtin_isfinite``
4172 * ``__builtin_isnan``
4173 * ``__builtin_isnormal``
4175 * ``__builtin_nans``
4176 * ``__builtin_parity``
4177 * ``__builtin_parityl``
4178 * ``__builtin_parityll``
4179 * ``__builtin_popcount``
4180 * ``__builtin_popcountl``
4181 * ``__builtin_popcountll``
4182 * ``__builtin_rotateleft8``
4183 * ``__builtin_rotateleft16``
4184 * ``__builtin_rotateleft32``
4185 * ``__builtin_rotateleft64``
4186 * ``__builtin_rotateright8``
4187 * ``__builtin_rotateright16``
4188 * ``__builtin_rotateright32``
4189 * ``__builtin_rotateright64``
4191 The following x86-specific intrinsics can be used in constant expressions:
4193 * ``_bit_scan_forward``
4194 * ``_bit_scan_reverse``
4207 * ``_mm_popcnt_u32``
4208 * ``_mm_popcnt_u64``