1 =========================
2 Clang Language Extensions
3 =========================
15 AutomaticReferenceCounting
20 This document describes the language extensions provided by Clang. In addition
21 to the language extensions listed here, Clang aims to support a broad range of
22 GCC extensions. Please see the `GCC manual
23 <http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on
26 .. _langext-feature_check:
28 Feature Checking Macros
29 =======================
31 Language extensions can be very useful, but only if you know you can depend on
32 them. In order to allow fine-grain features checks, we support three builtin
33 function-like macros. This allows you to directly test for a feature in your
34 code without having to resort to something like autoconf or fragile "compiler
40 This function-like macro takes a single identifier argument that is the name of
41 a builtin function. It evaluates to 1 if the builtin is supported or 0 if not.
42 It can be used like this:
46 #ifndef __has_builtin // Optional of course.
47 #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
51 #if __has_builtin(__builtin_trap)
58 .. _langext-__has_feature-__has_extension:
60 ``__has_feature`` and ``__has_extension``
61 -----------------------------------------
63 These function-like macros take a single identifier argument that is the name
64 of a feature. ``__has_feature`` evaluates to 1 if the feature is both
65 supported by Clang and standardized in the current language standard or 0 if
66 not (but see :ref:`below <langext-has-feature-back-compat>`), while
67 ``__has_extension`` evaluates to 1 if the feature is supported by Clang in the
68 current language (either as a language extension or a standard language
69 feature) or 0 if not. They can be used like this:
73 #ifndef __has_feature // Optional of course.
74 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
76 #ifndef __has_extension
77 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
81 #if __has_feature(cxx_rvalue_references)
82 // This code will only be compiled with the -std=c++11 and -std=gnu++11
83 // options, because rvalue references are only standardized in C++11.
86 #if __has_extension(cxx_rvalue_references)
87 // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98
88 // and -std=gnu++98 options, because rvalue references are supported as a
89 // language extension in C++98.
92 .. _langext-has-feature-back-compat:
94 For backward compatibility, ``__has_feature`` can also be used to test
95 for support for non-standardized features, i.e. features not prefixed ``c_``,
96 ``cxx_`` or ``objc_``.
98 Another use of ``__has_feature`` is to check for compiler features not related
99 to the language standard, such as e.g. :doc:`AddressSanitizer
102 If the ``-pedantic-errors`` option is given, ``__has_extension`` is equivalent
103 to ``__has_feature``.
105 The feature tag is described along with the language feature below.
107 The feature name or extension name can also be specified with a preceding and
108 following ``__`` (double underscore) to avoid interference from a macro with
109 the same name. For instance, ``__cxx_rvalue_references__`` can be used instead
110 of ``cxx_rvalue_references``.
112 ``__has_cpp_attribute``
113 -----------------------
115 This function-like macro takes a single argument that is the name of a
116 C++11-style attribute. The argument can either be a single identifier, or a
117 scoped identifier. If the attribute is supported, a nonzero value is returned.
118 If the attribute is a standards-based attribute, this macro returns a nonzero
119 value based on the year and month in which the attribute was voted into the
120 working draft. If the attribute is not supported by the current compliation
121 target, this macro evaluates to 0. It can be used like this:
125 #ifndef __has_cpp_attribute // Optional of course.
126 #define __has_cpp_attribute(x) 0 // Compatibility with non-clang compilers.
130 #if __has_cpp_attribute(clang::fallthrough)
131 #define FALLTHROUGH [[clang::fallthrough]]
137 The attribute identifier (but not scope) can also be specified with a preceding
138 and following ``__`` (double underscore) to avoid interference from a macro with
139 the same name. For instance, ``gnu::__const__`` can be used instead of
142 ``__has_c_attribute``
143 ---------------------
145 This function-like macro takes a single argument that is the name of an
146 attribute exposed with the double square-bracket syntax in C mode. The argument
147 can either be a single identifier or a scoped identifier. If the attribute is
148 supported, a nonzero value is returned. If the attribute is not supported by the
149 current compilation target, this macro evaluates to 0. It can be used like this:
153 #ifndef __has_c_attribute // Optional of course.
154 #define __has_c_attribute(x) 0 // Compatibility with non-clang compilers.
158 #if __has_c_attribute(fallthrough)
159 #define FALLTHROUGH [[fallthrough]]
165 The attribute identifier (but not scope) can also be specified with a preceding
166 and following ``__`` (double underscore) to avoid interference from a macro with
167 the same name. For instance, ``gnu::__const__`` can be used instead of
174 This function-like macro takes a single identifier argument that is the name of
175 a GNU-style attribute. It evaluates to 1 if the attribute is supported by the
176 current compilation target, or 0 if not. It can be used like this:
180 #ifndef __has_attribute // Optional of course.
181 #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
185 #if __has_attribute(always_inline)
186 #define ALWAYS_INLINE __attribute__((always_inline))
188 #define ALWAYS_INLINE
192 The attribute name can also be specified with a preceding and following ``__``
193 (double underscore) to avoid interference from a macro with the same name. For
194 instance, ``__always_inline__`` can be used instead of ``always_inline``.
197 ``__has_declspec_attribute``
198 ----------------------------
200 This function-like macro takes a single identifier argument that is the name of
201 an attribute implemented as a Microsoft-style ``__declspec`` attribute. It
202 evaluates to 1 if the attribute is supported by the current compilation target,
203 or 0 if not. It can be used like this:
207 #ifndef __has_declspec_attribute // Optional of course.
208 #define __has_declspec_attribute(x) 0 // Compatibility with non-clang compilers.
212 #if __has_declspec_attribute(dllexport)
213 #define DLLEXPORT __declspec(dllexport)
219 The attribute name can also be specified with a preceding and following ``__``
220 (double underscore) to avoid interference from a macro with the same name. For
221 instance, ``__dllexport__`` can be used instead of ``dllexport``.
226 This function-like macro takes a single identifier argument that might be either
227 a reserved word or a regular identifier. It evaluates to 1 if the argument is just
228 a regular identifier and not a reserved word, in the sense that it can then be
229 used as the name of a user-defined function or variable. Otherwise it evaluates
230 to 0. It can be used like this:
235 #ifdef __is_identifier // Compatibility with non-clang compilers.
236 #if __is_identifier(__wchar_t)
237 typedef wchar_t __wchar_t;
241 __wchar_t WideCharacter;
244 Include File Checking Macros
245 ============================
247 Not all developments systems have the same include files. The
248 :ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow
249 you to check for the existence of an include file before doing a possibly
250 failing ``#include`` directive. Include file checking macros must be used
251 as expressions in ``#if`` or ``#elif`` preprocessing directives.
253 .. _langext-__has_include:
258 This function-like macro takes a single file name string argument that is the
259 name of an include file. It evaluates to 1 if the file can be found using the
260 include paths, or 0 otherwise:
264 // Note the two possible file name string formats.
265 #if __has_include("myinclude.h") && __has_include(<stdint.h>)
266 # include "myinclude.h"
269 To test for this feature, use ``#if defined(__has_include)``:
273 // To avoid problem with non-clang compilers not having this macro.
274 #if defined(__has_include)
275 #if __has_include("myinclude.h")
276 # include "myinclude.h"
280 .. _langext-__has_include_next:
282 ``__has_include_next``
283 ----------------------
285 This function-like macro takes a single file name string argument that is the
286 name of an include file. It is like ``__has_include`` except that it looks for
287 the second instance of the given file found in the include paths. It evaluates
288 to 1 if the second instance of the file can be found using the include paths,
293 // Note the two possible file name string formats.
294 #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)
295 # include_next "myinclude.h"
298 // To avoid problem with non-clang compilers not having this macro.
299 #if defined(__has_include_next)
300 #if __has_include_next("myinclude.h")
301 # include_next "myinclude.h"
305 Note that ``__has_include_next``, like the GNU extension ``#include_next``
306 directive, is intended for use in headers only, and will issue a warning if
307 used in the top-level compilation file. A warning will also be issued if an
308 absolute path is used in the file argument.
313 This function-like macro takes a string literal that represents a command line
314 option for a warning and returns true if that is a valid warning option.
318 #if __has_warning("-Wformat")
326 Defined to a string that contains the name of the main input file passed to
330 Defined to an integer value that starts at zero and is incremented each time
331 the ``__COUNTER__`` macro is expanded.
333 ``__INCLUDE_LEVEL__``
334 Defined to an integral value that is the include depth of the file currently
335 being translated. For the main file, this value is zero.
338 Defined to the date and time of the last modification of the current source
342 Defined when compiling with Clang
345 Defined to the major marketing version number of Clang (e.g., the 2 in
346 2.0.1). Note that marketing version numbers should not be used to check for
347 language features, as different vendors use different numbering schemes.
348 Instead, use the :ref:`langext-feature_check`.
351 Defined to the minor version number of Clang (e.g., the 0 in 2.0.1). Note
352 that marketing version numbers should not be used to check for language
353 features, as different vendors use different numbering schemes. Instead, use
354 the :ref:`langext-feature_check`.
356 ``__clang_patchlevel__``
357 Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).
359 ``__clang_version__``
360 Defined to a string that captures the Clang marketing version, including the
361 Subversion tag or revision number, e.g., "``1.5 (trunk 102332)``".
365 Vectors and Extended Vectors
366 ============================
368 Supports the GCC, OpenCL, AltiVec and NEON vector extensions.
370 OpenCL vector types are created using ``ext_vector_type`` attribute. It
371 support for ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example
376 typedef float float4 __attribute__((ext_vector_type(4)));
377 typedef float float2 __attribute__((ext_vector_type(2)));
379 float4 foo(float2 a, float2 b) {
386 Query for this feature with ``__has_extension(attribute_ext_vector_type)``.
388 Giving ``-maltivec`` option to clang enables support for AltiVec vector syntax
389 and functions. For example:
393 vector float foo(vector int a) {
395 b = vec_add(a, a) + a;
396 return (vector float)b;
399 NEON vector types are created using ``neon_vector_type`` and
400 ``neon_polyvector_type`` attributes. For example:
404 typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t;
405 typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t;
407 int8x8_t foo(int8x8_t a) {
416 Vector literals can be used to create vectors from a set of scalars, or
417 vectors. Either parentheses or braces form can be used. In the parentheses
418 form the number of literal values specified must be one, i.e. referring to a
419 scalar value, or must match the size of the vector type being created. If a
420 single scalar literal value is specified, the scalar literal value will be
421 replicated to all the components of the vector type. In the brackets form any
422 number of literals can be specified. For example:
426 typedef int v4si __attribute__((__vector_size__(16)));
427 typedef float float4 __attribute__((ext_vector_type(4)));
428 typedef float float2 __attribute__((ext_vector_type(2)));
430 v4si vsi = (v4si){1, 2, 3, 4};
431 float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f);
432 vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1).
433 vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0).
434 vector int vi3 = (vector int)(1, 2); // error
435 vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0).
436 vector int vi5 = (vector int)(1, 2, 3, 4);
437 float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f));
442 The table below shows the support for each operation by vector extension. A
443 dash indicates that an operation is not accepted according to a corresponding
446 ============================== ======= ======= ======= =======
447 Operator OpenCL AltiVec GCC NEON
448 ============================== ======= ======= ======= =======
450 unary operators +, -- yes yes yes --
451 ++, -- -- yes yes yes --
452 +,--,*,/,% yes yes yes --
453 bitwise operators &,|,^,~ yes yes yes --
455 !, &&, || yes -- -- --
456 ==, !=, >, <, >=, <= yes yes -- --
459 sizeof yes yes yes yes
460 C-style cast yes yes yes no
461 reinterpret_cast yes no yes no
462 static_cast yes no yes no
463 const_cast no no no no
464 ============================== ======= ======= ======= =======
466 See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`.
468 Half-Precision Floating Point
469 =============================
471 Clang supports two half-precision (16-bit) floating point types: ``__fp16`` and
472 ``_Float16``. ``__fp16`` is defined in the ARM C Language Extensions (`ACLE
473 <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053d/IHI0053D_acle_2_1.pdf>`_)
474 and ``_Float16`` in ISO/IEC TS 18661-3:2015.
476 ``__fp16`` is a storage and interchange format only. This means that values of
477 ``__fp16`` promote to (at least) float when used in arithmetic operations.
478 There are two ``__fp16`` formats. Clang supports the IEEE 754-2008 format and
479 not the ARM alternative format.
481 ISO/IEC TS 18661-3:2015 defines C support for additional floating point types.
482 ``_FloatN`` is defined as a binary floating type, where the N suffix denotes
483 the number of bits and is 16, 32, 64, or greater and equal to 128 and a
484 multiple of 32. Clang supports ``_Float16``. The difference from ``__fp16`` is
485 that arithmetic on ``_Float16`` is performed in half-precision, thus it is not
486 a storage-only format. ``_Float16`` is available as a source language type in
489 It is recommended that portable code use the ``_Float16`` type because
490 ``__fp16`` is an ARM C-Language Extension (ACLE), whereas ``_Float16`` is
491 defined by the C standards committee, so using ``_Float16`` will not prevent
492 code from being ported to architectures other than Arm. Also, ``_Float16``
493 arithmetic and operations will directly map on half-precision instructions when
494 they are available (e.g. Armv8.2-A), avoiding conversions to/from
495 single-precision, and thus will result in more performant code. If
496 half-precision instructions are unavailable, values will be promoted to
497 single-precision, similar to the semantics of ``__fp16`` except that the
498 results will be stored in single-precision.
500 In an arithmetic operation where one operand is of ``__fp16`` type and the
501 other is of ``_Float16`` type, the ``_Float16`` type is first converted to
502 ``__fp16`` type and then the operation is completed as if both operands were of
505 To define a ``_Float16`` literal, suffix ``f16`` can be appended to the compile-time
506 constant declaration. There is no default argument promotion for ``_Float16``; this
507 applies to the standard floating types only. As a consequence, for example, an
508 explicit cast is required for printing a ``_Float16`` value (there is no string
509 format specifier for ``_Float16``).
511 Messages on ``deprecated`` and ``unavailable`` Attributes
512 =========================================================
514 An optional string message can be added to the ``deprecated`` and
515 ``unavailable`` attributes. For example:
519 void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));
521 If the deprecated or unavailable declaration is used, the message will be
522 incorporated into the appropriate diagnostic:
526 harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
527 [-Wdeprecated-declarations]
531 Query for this feature with
532 ``__has_extension(attribute_deprecated_with_message)`` and
533 ``__has_extension(attribute_unavailable_with_message)``.
535 Attributes on Enumerators
536 =========================
538 Clang allows attributes to be written on individual enumerators. This allows
539 enumerators to be deprecated, made unavailable, etc. The attribute must appear
540 after the enumerator name and before any initializer, like so:
547 OM_Terrified __attribute__((deprecated)),
548 OM_AbortOnError __attribute__((deprecated)) = 4
551 Attributes on the ``enum`` declaration do not apply to individual enumerators.
553 Query for this feature with ``__has_extension(enumerator_attributes)``.
555 'User-Specified' System Frameworks
556 ==================================
558 Clang provides a mechanism by which frameworks can be built in such a way that
559 they will always be treated as being "system frameworks", even if they are not
560 present in a system framework directory. This can be useful to system
561 framework developers who want to be able to test building other applications
562 with development builds of their framework, including the manner in which the
563 compiler changes warning behavior for system headers.
565 Framework developers can opt-in to this mechanism by creating a
566 "``.system_framework``" file at the top-level of their framework. That is, the
567 framework should have contents like:
571 .../TestFramework.framework
572 .../TestFramework.framework/.system_framework
573 .../TestFramework.framework/Headers
574 .../TestFramework.framework/Headers/TestFramework.h
577 Clang will treat the presence of this file as an indicator that the framework
578 should be treated as a system framework, regardless of how it was found in the
579 framework search path. For consistency, we recommend that such files never be
580 included in installed versions of the framework.
582 Checks for Standard Language Features
583 =====================================
585 The ``__has_feature`` macro can be used to query if certain standard language
586 features are enabled. The ``__has_extension`` macro can be used to query if
587 language features are available as an extension when compiling for a standard
588 which does not provide them. The features which can be tested are listed here.
590 Since Clang 3.4, the C++ SD-6 feature test macros are also supported.
591 These are macros with names of the form ``__cpp_<feature_name>``, and are
592 intended to be a portable way to query the supported features of the compiler.
593 See `the C++ status page <http://clang.llvm.org/cxx_status.html#ts>`_ for
594 information on the version of SD-6 supported by each Clang release, and the
595 macros provided by that revision of the recommendations.
600 The features listed below are part of the C++98 standard. These features are
601 enabled by default when compiling C++ code.
606 Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been
607 enabled. For example, compiling code with ``-fno-exceptions`` disables C++
613 Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For
614 example, compiling code with ``-fno-rtti`` disables the use of RTTI.
619 The features listed below are part of the C++11 standard. As a result, all
620 these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option
621 when compiling C++ code.
623 C++11 SFINAE includes access control
624 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
626 Use ``__has_feature(cxx_access_control_sfinae)`` or
627 ``__has_extension(cxx_access_control_sfinae)`` to determine whether
628 access-control errors (e.g., calling a private constructor) are considered to
629 be template argument deduction errors (aka SFINAE errors), per `C++ DR1170
630 <http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170>`_.
632 C++11 alias templates
633 ^^^^^^^^^^^^^^^^^^^^^
635 Use ``__has_feature(cxx_alias_templates)`` or
636 ``__has_extension(cxx_alias_templates)`` to determine if support for C++11's
637 alias declarations and alias templates is enabled.
639 C++11 alignment specifiers
640 ^^^^^^^^^^^^^^^^^^^^^^^^^^
642 Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to
643 determine if support for alignment specifiers using ``alignas`` is enabled.
645 Use ``__has_feature(cxx_alignof)`` or ``__has_extension(cxx_alignof)`` to
646 determine if support for the ``alignof`` keyword is enabled.
651 Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to
652 determine if support for attribute parsing with C++11's square bracket notation
655 C++11 generalized constant expressions
656 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
658 Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized
659 constant expressions (e.g., ``constexpr``) is enabled.
664 Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to
665 determine if support for the ``decltype()`` specifier is enabled. C++11's
666 ``decltype`` does not require type-completeness of a function call expression.
667 Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or
668 ``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if
669 support for this feature is enabled.
671 C++11 default template arguments in function templates
672 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
674 Use ``__has_feature(cxx_default_function_template_args)`` or
675 ``__has_extension(cxx_default_function_template_args)`` to determine if support
676 for default template arguments in function templates is enabled.
678 C++11 ``default``\ ed functions
679 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
681 Use ``__has_feature(cxx_defaulted_functions)`` or
682 ``__has_extension(cxx_defaulted_functions)`` to determine if support for
683 defaulted function definitions (with ``= default``) is enabled.
685 C++11 delegating constructors
686 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
688 Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for
689 delegating constructors is enabled.
691 C++11 ``deleted`` functions
692 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
694 Use ``__has_feature(cxx_deleted_functions)`` or
695 ``__has_extension(cxx_deleted_functions)`` to determine if support for deleted
696 function definitions (with ``= delete``) is enabled.
698 C++11 explicit conversion functions
699 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
701 Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for
702 ``explicit`` conversion functions is enabled.
704 C++11 generalized initializers
705 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
707 Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for
708 generalized initializers (using braced lists and ``std::initializer_list``) is
711 C++11 implicit move constructors/assignment operators
712 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
714 Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly
715 generate move constructors and move assignment operators where needed.
717 C++11 inheriting constructors
718 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
720 Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for
721 inheriting constructors is enabled.
723 C++11 inline namespaces
724 ^^^^^^^^^^^^^^^^^^^^^^^
726 Use ``__has_feature(cxx_inline_namespaces)`` or
727 ``__has_extension(cxx_inline_namespaces)`` to determine if support for inline
728 namespaces is enabled.
733 Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to
734 determine if support for lambdas is enabled.
736 C++11 local and unnamed types as template arguments
737 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
739 Use ``__has_feature(cxx_local_type_template_args)`` or
740 ``__has_extension(cxx_local_type_template_args)`` to determine if support for
741 local and unnamed types as template arguments is enabled.
746 Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to
747 determine if support for noexcept exception specifications is enabled.
749 C++11 in-class non-static data member initialization
750 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
752 Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class
753 initialization of non-static data members is enabled.
758 Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to
759 determine if support for ``nullptr`` is enabled.
761 C++11 ``override control``
762 ^^^^^^^^^^^^^^^^^^^^^^^^^^
764 Use ``__has_feature(cxx_override_control)`` or
765 ``__has_extension(cxx_override_control)`` to determine if support for the
766 override control keywords is enabled.
768 C++11 reference-qualified functions
769 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
771 Use ``__has_feature(cxx_reference_qualified_functions)`` or
772 ``__has_extension(cxx_reference_qualified_functions)`` to determine if support
773 for reference-qualified functions (e.g., member functions with ``&`` or ``&&``
774 applied to ``*this``) is enabled.
776 C++11 range-based ``for`` loop
777 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
779 Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to
780 determine if support for the range-based for loop is enabled.
782 C++11 raw string literals
783 ^^^^^^^^^^^^^^^^^^^^^^^^^
785 Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw
786 string literals (e.g., ``R"x(foo\bar)x"``) is enabled.
788 C++11 rvalue references
789 ^^^^^^^^^^^^^^^^^^^^^^^
791 Use ``__has_feature(cxx_rvalue_references)`` or
792 ``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue
793 references is enabled.
795 C++11 ``static_assert()``
796 ^^^^^^^^^^^^^^^^^^^^^^^^^
798 Use ``__has_feature(cxx_static_assert)`` or
799 ``__has_extension(cxx_static_assert)`` to determine if support for compile-time
800 assertions using ``static_assert`` is enabled.
802 C++11 ``thread_local``
803 ^^^^^^^^^^^^^^^^^^^^^^
805 Use ``__has_feature(cxx_thread_local)`` to determine if support for
806 ``thread_local`` variables is enabled.
811 Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to
812 determine C++11 type inference is supported using the ``auto`` specifier. If
813 this is disabled, ``auto`` will instead be a storage class specifier, as in C
816 C++11 strongly typed enumerations
817 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
819 Use ``__has_feature(cxx_strong_enums)`` or
820 ``__has_extension(cxx_strong_enums)`` to determine if support for strongly
821 typed, scoped enumerations is enabled.
823 C++11 trailing return type
824 ^^^^^^^^^^^^^^^^^^^^^^^^^^
826 Use ``__has_feature(cxx_trailing_return)`` or
827 ``__has_extension(cxx_trailing_return)`` to determine if support for the
828 alternate function declaration syntax with trailing return type is enabled.
830 C++11 Unicode string literals
831 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
833 Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode
834 string literals is enabled.
836 C++11 unrestricted unions
837 ^^^^^^^^^^^^^^^^^^^^^^^^^
839 Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for
840 unrestricted unions is enabled.
842 C++11 user-defined literals
843 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
845 Use ``__has_feature(cxx_user_literals)`` to determine if support for
846 user-defined literals is enabled.
848 C++11 variadic templates
849 ^^^^^^^^^^^^^^^^^^^^^^^^
851 Use ``__has_feature(cxx_variadic_templates)`` or
852 ``__has_extension(cxx_variadic_templates)`` to determine if support for
853 variadic templates is enabled.
858 The features listed below are part of the C++14 standard. As a result, all
859 these features are enabled with the ``-std=C++14`` or ``-std=gnu++14`` option
860 when compiling C++ code.
862 C++14 binary literals
863 ^^^^^^^^^^^^^^^^^^^^^
865 Use ``__has_feature(cxx_binary_literals)`` or
866 ``__has_extension(cxx_binary_literals)`` to determine whether
867 binary literals (for instance, ``0b10010``) are recognized. Clang supports this
868 feature as an extension in all language modes.
870 C++14 contextual conversions
871 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
873 Use ``__has_feature(cxx_contextual_conversions)`` or
874 ``__has_extension(cxx_contextual_conversions)`` to determine if the C++14 rules
875 are used when performing an implicit conversion for an array bound in a
876 *new-expression*, the operand of a *delete-expression*, an integral constant
877 expression, or a condition in a ``switch`` statement.
882 Use ``__has_feature(cxx_decltype_auto)`` or
883 ``__has_extension(cxx_decltype_auto)`` to determine if support
884 for the ``decltype(auto)`` placeholder type is enabled.
886 C++14 default initializers for aggregates
887 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
889 Use ``__has_feature(cxx_aggregate_nsdmi)`` or
890 ``__has_extension(cxx_aggregate_nsdmi)`` to determine if support
891 for default initializers in aggregate members is enabled.
893 C++14 digit separators
894 ^^^^^^^^^^^^^^^^^^^^^^
896 Use ``__cpp_digit_separators`` to determine if support for digit separators
897 using single quotes (for instance, ``10'000``) is enabled. At this time, there
898 is no corresponding ``__has_feature`` name
900 C++14 generalized lambda capture
901 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
903 Use ``__has_feature(cxx_init_captures)`` or
904 ``__has_extension(cxx_init_captures)`` to determine if support for
905 lambda captures with explicit initializers is enabled
906 (for instance, ``[n(0)] { return ++n; }``).
908 C++14 generic lambdas
909 ^^^^^^^^^^^^^^^^^^^^^
911 Use ``__has_feature(cxx_generic_lambdas)`` or
912 ``__has_extension(cxx_generic_lambdas)`` to determine if support for generic
913 (polymorphic) lambdas is enabled
914 (for instance, ``[] (auto x) { return x + 1; }``).
916 C++14 relaxed constexpr
917 ^^^^^^^^^^^^^^^^^^^^^^^
919 Use ``__has_feature(cxx_relaxed_constexpr)`` or
920 ``__has_extension(cxx_relaxed_constexpr)`` to determine if variable
921 declarations, local variable modification, and control flow constructs
922 are permitted in ``constexpr`` functions.
924 C++14 return type deduction
925 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
927 Use ``__has_feature(cxx_return_type_deduction)`` or
928 ``__has_extension(cxx_return_type_deduction)`` to determine if support
929 for return type deduction for functions (using ``auto`` as a return type)
932 C++14 runtime-sized arrays
933 ^^^^^^^^^^^^^^^^^^^^^^^^^^
935 Use ``__has_feature(cxx_runtime_array)`` or
936 ``__has_extension(cxx_runtime_array)`` to determine if support
937 for arrays of runtime bound (a restricted form of variable-length arrays)
939 Clang's implementation of this feature is incomplete.
941 C++14 variable templates
942 ^^^^^^^^^^^^^^^^^^^^^^^^
944 Use ``__has_feature(cxx_variable_templates)`` or
945 ``__has_extension(cxx_variable_templates)`` to determine if support for
946 templated variable declarations is enabled.
951 The features listed below are part of the C11 standard. As a result, all these
952 features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when
953 compiling C code. Additionally, because these features are all
954 backward-compatible, they are available as extensions in all language modes.
956 C11 alignment specifiers
957 ^^^^^^^^^^^^^^^^^^^^^^^^
959 Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine
960 if support for alignment specifiers using ``_Alignas`` is enabled.
962 Use ``__has_feature(c_alignof)`` or ``__has_extension(c_alignof)`` to determine
963 if support for the ``_Alignof`` keyword is enabled.
965 C11 atomic operations
966 ^^^^^^^^^^^^^^^^^^^^^
968 Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine
969 if support for atomic types using ``_Atomic`` is enabled. Clang also provides
970 :ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement
971 the ``<stdatomic.h>`` operations on ``_Atomic`` types. Use
972 ``__has_include(<stdatomic.h>)`` to determine if C11's ``<stdatomic.h>`` header
975 Clang will use the system's ``<stdatomic.h>`` header when one is available, and
976 will otherwise use its own. When using its own, implementations of the atomic
977 operations are provided as macros. In the cases where C11 also requires a real
978 function, this header provides only the declaration of that function (along
979 with a shadowing macro implementation), and you must link to a library which
980 provides a definition of the function if you use it instead of the macro.
982 C11 generic selections
983 ^^^^^^^^^^^^^^^^^^^^^^
985 Use ``__has_feature(c_generic_selections)`` or
986 ``__has_extension(c_generic_selections)`` to determine if support for generic
987 selections is enabled.
989 As an extension, the C11 generic selection expression is available in all
990 languages supported by Clang. The syntax is the same as that given in the C11
993 In C, type compatibility is decided according to the rules given in the
994 appropriate standard, but in C++, which lacks the type compatibility rules used
995 in C, types are considered compatible only if they are equivalent.
997 C11 ``_Static_assert()``
998 ^^^^^^^^^^^^^^^^^^^^^^^^
1000 Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)``
1001 to determine if support for compile-time assertions using ``_Static_assert`` is
1004 C11 ``_Thread_local``
1005 ^^^^^^^^^^^^^^^^^^^^^
1007 Use ``__has_feature(c_thread_local)`` or ``__has_extension(c_thread_local)``
1008 to determine if support for ``_Thread_local`` variables is enabled.
1013 Use ``__has_feature(modules)`` to determine if Modules have been enabled.
1014 For example, compiling code with ``-fmodules`` enables the use of Modules.
1016 More information could be found `here <http://clang.llvm.org/docs/Modules.html>`_.
1018 Checks for Type Trait Primitives
1019 ================================
1021 Type trait primitives are special builtin constant expressions that can be used
1022 by the standard C++ library to facilitate or simplify the implementation of
1023 user-facing type traits in the <type_traits> header.
1025 They are not intended to be used directly by user code because they are
1026 implementation-defined and subject to change -- as such they're tied closely to
1027 the supported set of system headers, currently:
1031 * The Microsoft standard C++ library
1033 Clang supports the `GNU C++ type traits
1034 <http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the
1035 `Microsoft Visual C++ Type traits
1036 <http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_.
1038 Feature detection is supported only for some of the primitives at present. User
1039 code should not use these checks because they bear no direct relation to the
1040 actual set of type traits supported by the C++ standard library.
1042 For type trait ``__X``, ``__has_extension(X)`` indicates the presence of the
1043 type trait primitive in the compiler. A simplistic usage example as might be
1044 seen in standard C++ headers follows:
1048 #if __has_extension(is_convertible_to)
1049 template<typename From, typename To>
1050 struct is_convertible_to {
1051 static const bool value = __is_convertible_to(From, To);
1054 // Emulate type trait for compatibility with other compilers.
1057 The following type trait primitives are supported by Clang:
1059 * ``__has_nothrow_assign`` (GNU, Microsoft)
1060 * ``__has_nothrow_copy`` (GNU, Microsoft)
1061 * ``__has_nothrow_constructor`` (GNU, Microsoft)
1062 * ``__has_trivial_assign`` (GNU, Microsoft)
1063 * ``__has_trivial_copy`` (GNU, Microsoft)
1064 * ``__has_trivial_constructor`` (GNU, Microsoft)
1065 * ``__has_trivial_destructor`` (GNU, Microsoft)
1066 * ``__has_virtual_destructor`` (GNU, Microsoft)
1067 * ``__is_abstract`` (GNU, Microsoft)
1068 * ``__is_aggregate`` (GNU, Microsoft)
1069 * ``__is_base_of`` (GNU, Microsoft)
1070 * ``__is_class`` (GNU, Microsoft)
1071 * ``__is_convertible_to`` (Microsoft)
1072 * ``__is_empty`` (GNU, Microsoft)
1073 * ``__is_enum`` (GNU, Microsoft)
1074 * ``__is_interface_class`` (Microsoft)
1075 * ``__is_pod`` (GNU, Microsoft)
1076 * ``__is_polymorphic`` (GNU, Microsoft)
1077 * ``__is_union`` (GNU, Microsoft)
1078 * ``__is_literal(type)``: Determines whether the given type is a literal type
1079 * ``__is_final``: Determines whether the given type is declared with a
1080 ``final`` class-virt-specifier.
1081 * ``__underlying_type(type)``: Retrieves the underlying type for a given
1082 ``enum`` type. This trait is required to implement the C++11 standard
1084 * ``__is_trivially_assignable(totype, fromtype)``: Determines whether a value
1085 of type ``totype`` can be assigned to from a value of type ``fromtype`` such
1086 that no non-trivial functions are called as part of that assignment. This
1087 trait is required to implement the C++11 standard library.
1088 * ``__is_trivially_constructible(type, argtypes...)``: Determines whether a
1089 value of type ``type`` can be direct-initialized with arguments of types
1090 ``argtypes...`` such that no non-trivial functions are called as part of
1091 that initialization. This trait is required to implement the C++11 standard
1093 * ``__is_destructible`` (MSVC 2013)
1094 * ``__is_nothrow_destructible`` (MSVC 2013)
1095 * ``__is_nothrow_assignable`` (MSVC 2013, clang)
1096 * ``__is_constructible`` (MSVC 2013, clang)
1097 * ``__is_nothrow_constructible`` (MSVC 2013, clang)
1098 * ``__is_assignable`` (MSVC 2015, clang)
1099 * ``__reference_binds_to_temporary(T, U)`` (Clang): Determines whether a
1100 reference of type ``T`` bound to an expression of type ``U`` would bind to a
1101 materialized temporary object. If ``T`` is not a reference type the result
1102 is false. Note this trait will also return false when the initialization of
1103 ``T`` from ``U`` is ill-formed.
1108 The syntax and high level language feature description is in
1109 :doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for
1110 the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`.
1112 Query for this feature with ``__has_extension(blocks)``.
1114 Objective-C Features
1115 ====================
1117 Related result types
1118 --------------------
1120 According to Cocoa conventions, Objective-C methods with certain names
1121 ("``init``", "``alloc``", etc.) always return objects that are an instance of
1122 the receiving class's type. Such methods are said to have a "related result
1123 type", meaning that a message send to one of these methods will have the same
1124 static type as an instance of the receiver class. For example, given the
1127 .. code-block:: objc
1134 @interface NSArray : NSObject
1137 and this common initialization pattern
1139 .. code-block:: objc
1141 NSArray *array = [[NSArray alloc] init];
1143 the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because
1144 ``alloc`` implicitly has a related result type. Similarly, the type of the
1145 expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a
1146 related result type and its receiver is known to have the type ``NSArray *``.
1147 If neither ``alloc`` nor ``init`` had a related result type, the expressions
1148 would have had type ``id``, as declared in the method signature.
1150 A method with a related result type can be declared by using the type
1151 ``instancetype`` as its result type. ``instancetype`` is a contextual keyword
1152 that is only permitted in the result type of an Objective-C method, e.g.
1154 .. code-block:: objc
1157 + (instancetype)constructAnA;
1160 The related result type can also be inferred for some methods. To determine
1161 whether a method has an inferred related result type, the first word in the
1162 camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered,
1163 and the method will have a related result type if its return type is compatible
1164 with the type of its class and if:
1166 * the first word is "``alloc``" or "``new``", and the method is a class method,
1169 * the first word is "``autorelease``", "``init``", "``retain``", or "``self``",
1170 and the method is an instance method.
1172 If a method with a related result type is overridden by a subclass method, the
1173 subclass method must also return a type that is compatible with the subclass
1176 .. code-block:: objc
1178 @interface NSString : NSObject
1179 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
1182 Related result types only affect the type of a message send or property access
1183 via the given method. In all other respects, a method with a related result
1184 type is treated the same way as method that returns ``id``.
1186 Use ``__has_feature(objc_instancetype)`` to determine whether the
1187 ``instancetype`` contextual keyword is available.
1189 Automatic reference counting
1190 ----------------------------
1192 Clang provides support for :doc:`automated reference counting
1193 <AutomaticReferenceCounting>` in Objective-C, which eliminates the need
1194 for manual ``retain``/``release``/``autorelease`` message sends. There are three
1195 feature macros associated with automatic reference counting:
1196 ``__has_feature(objc_arc)`` indicates the availability of automated reference
1197 counting in general, while ``__has_feature(objc_arc_weak)`` indicates that
1198 automated reference counting also includes support for ``__weak`` pointers to
1199 Objective-C objects. ``__has_feature(objc_arc_fields)`` indicates that C structs
1200 are allowed to have fields that are pointers to Objective-C objects managed by
1201 automatic reference counting.
1208 Clang supports ARC-style weak and unsafe references in Objective-C even
1209 outside of ARC mode. Weak references must be explicitly enabled with
1210 the ``-fobjc-weak`` option; use ``__has_feature((objc_arc_weak))``
1211 to test whether they are enabled. Unsafe references are enabled
1212 unconditionally. ARC-style weak and unsafe references cannot be used
1213 when Objective-C garbage collection is enabled.
1215 Except as noted below, the language rules for the ``__weak`` and
1216 ``__unsafe_unretained`` qualifiers (and the ``weak`` and
1217 ``unsafe_unretained`` property attributes) are just as laid out
1218 in the :doc:`ARC specification <AutomaticReferenceCounting>`.
1219 In particular, note that some classes do not support forming weak
1220 references to their instances, and note that special care must be
1221 taken when storing weak references in memory where initialization
1222 and deinitialization are outside the responsibility of the compiler
1223 (such as in ``malloc``-ed memory).
1225 Loading from a ``__weak`` variable always implicitly retains the
1226 loaded value. In non-ARC modes, this retain is normally balanced
1227 by an implicit autorelease. This autorelease can be suppressed
1228 by performing the load in the receiver position of a ``-retain``
1229 message send (e.g. ``[weakReference retain]``); note that this performs
1230 only a single retain (the retain done when primitively loading from
1231 the weak reference).
1233 For the most part, ``__unsafe_unretained`` in non-ARC modes is just the
1234 default behavior of variables and therefore is not needed. However,
1235 it does have an effect on the semantics of block captures: normally,
1236 copying a block which captures an Objective-C object or block pointer
1237 causes the captured pointer to be retained or copied, respectively,
1238 but that behavior is suppressed when the captured variable is qualified
1239 with ``__unsafe_unretained``.
1241 Note that the ``__weak`` qualifier formerly meant the GC qualifier in
1242 all non-ARC modes and was silently ignored outside of GC modes. It now
1243 means the ARC-style qualifier in all non-GC modes and is no longer
1244 allowed if not enabled by either ``-fobjc-arc`` or ``-fobjc-weak``.
1245 It is expected that ``-fobjc-weak`` will eventually be enabled by default
1246 in all non-GC Objective-C modes.
1248 .. _objc-fixed-enum:
1250 Enumerations with a fixed underlying type
1251 -----------------------------------------
1253 Clang provides support for C++11 enumerations with a fixed underlying type
1254 within Objective-C. For example, one can write an enumeration type as:
1258 typedef enum : unsigned char { Red, Green, Blue } Color;
1260 This specifies that the underlying type, which is used to store the enumeration
1261 value, is ``unsigned char``.
1263 Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed
1264 underlying types is available in Objective-C.
1266 Interoperability with C++11 lambdas
1267 -----------------------------------
1269 Clang provides interoperability between C++11 lambdas and blocks-based APIs, by
1270 permitting a lambda to be implicitly converted to a block pointer with the
1271 corresponding signature. For example, consider an API such as ``NSArray``'s
1272 array-sorting method:
1274 .. code-block:: objc
1276 - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr;
1278 ``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult
1279 (^)(id, id)``, and parameters of this type are generally provided with block
1280 literals as arguments. However, one can also use a C++11 lambda so long as it
1281 provides the same signature (in this case, accepting two parameters of type
1282 ``id`` and returning an ``NSComparisonResult``):
1284 .. code-block:: objc
1286 NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11",
1288 const NSStringCompareOptions comparisonOptions
1289 = NSCaseInsensitiveSearch | NSNumericSearch |
1290 NSWidthInsensitiveSearch | NSForcedOrderingSearch;
1291 NSLocale *currentLocale = [NSLocale currentLocale];
1293 = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult {
1294 NSRange string1Range = NSMakeRange(0, [s1 length]);
1295 return [s1 compare:s2 options:comparisonOptions
1296 range:string1Range locale:currentLocale];
1298 NSLog(@"sorted: %@", sorted);
1300 This code relies on an implicit conversion from the type of the lambda
1301 expression (an unnamed, local class type called the *closure type*) to the
1302 corresponding block pointer type. The conversion itself is expressed by a
1303 conversion operator in that closure type that produces a block pointer with the
1304 same signature as the lambda itself, e.g.,
1306 .. code-block:: objc
1308 operator NSComparisonResult (^)(id, id)() const;
1310 This conversion function returns a new block that simply forwards the two
1311 parameters to the lambda object (which it captures by copy), then returns the
1312 result. The returned block is first copied (with ``Block_copy``) and then
1313 autoreleased. As an optimization, if a lambda expression is immediately
1314 converted to a block pointer (as in the first example, above), then the block
1315 is not copied and autoreleased: rather, it is given the same lifetime as a
1316 block literal written at that point in the program, which avoids the overhead
1317 of copying a block to the heap in the common case.
1319 The conversion from a lambda to a block pointer is only available in
1320 Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory
1321 management (autorelease).
1323 Object Literals and Subscripting
1324 --------------------------------
1326 Clang provides support for :doc:`Object Literals and Subscripting
1327 <ObjectiveCLiterals>` in Objective-C, which simplifies common Objective-C
1328 programming patterns, makes programs more concise, and improves the safety of
1329 container creation. There are several feature macros associated with object
1330 literals and subscripting: ``__has_feature(objc_array_literals)`` tests the
1331 availability of array literals; ``__has_feature(objc_dictionary_literals)``
1332 tests the availability of dictionary literals;
1333 ``__has_feature(objc_subscripting)`` tests the availability of object
1336 Objective-C Autosynthesis of Properties
1337 ---------------------------------------
1339 Clang provides support for autosynthesis of declared properties. Using this
1340 feature, clang provides default synthesis of those properties not declared
1341 @dynamic and not having user provided backing getter and setter methods.
1342 ``__has_feature(objc_default_synthesize_properties)`` checks for availability
1343 of this feature in version of clang being used.
1345 .. _langext-objc-retain-release:
1347 Objective-C retaining behavior attributes
1348 -----------------------------------------
1350 In Objective-C, functions and methods are generally assumed to follow the
1351 `Cocoa Memory Management
1352 <http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_
1353 conventions for ownership of object arguments and
1354 return values. However, there are exceptions, and so Clang provides attributes
1355 to allow these exceptions to be documented. This are used by ARC and the
1356 `static analyzer <http://clang-analyzer.llvm.org>`_ Some exceptions may be
1357 better described using the ``objc_method_family`` attribute instead.
1359 **Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``,
1360 ``ns_returns_autoreleased``, ``cf_returns_retained``, and
1361 ``cf_returns_not_retained`` attributes can be placed on methods and functions
1362 that return Objective-C or CoreFoundation objects. They are commonly placed at
1363 the end of a function prototype or method declaration:
1365 .. code-block:: objc
1367 id foo() __attribute__((ns_returns_retained));
1369 - (NSString *)bar:(int)x __attribute__((ns_returns_retained));
1371 The ``*_returns_retained`` attributes specify that the returned object has a +1
1372 retain count. The ``*_returns_not_retained`` attributes specify that the return
1373 object has a +0 retain count, even if the normal convention for its selector
1374 would be +1. ``ns_returns_autoreleased`` specifies that the returned object is
1375 +0, but is guaranteed to live at least as long as the next flush of an
1378 **Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on
1379 an parameter declaration; they specify that the argument is expected to have a
1380 +1 retain count, which will be balanced in some way by the function or method.
1381 The ``ns_consumes_self`` attribute can only be placed on an Objective-C
1382 method; it specifies that the method expects its ``self`` parameter to have a
1383 +1 retain count, which it will balance in some way.
1385 .. code-block:: objc
1387 void foo(__attribute__((ns_consumed)) NSString *string);
1389 - (void) bar __attribute__((ns_consumes_self));
1390 - (void) baz:(id) __attribute__((ns_consumed)) x;
1392 Further examples of these attributes are available in the static analyzer's `list of annotations for analysis
1393 <http://clang-analyzer.llvm.org/annotations.html#cocoa_mem>`_.
1395 Query for these features with ``__has_attribute(ns_consumed)``,
1396 ``__has_attribute(ns_returns_retained)``, etc.
1398 Objective-C @available
1399 ----------------------
1401 It is possible to use the newest SDK but still build a program that can run on
1402 older versions of macOS and iOS by passing ``-mmacosx-version-min=`` /
1403 ``-miphoneos-version-min=``.
1405 Before LLVM 5.0, when calling a function that exists only in the OS that's
1406 newer than the target OS (as determined by the minimum deployment version),
1407 programmers had to carefully check if the function exists at runtime, using
1408 null checks for weakly-linked C functions, ``+class`` for Objective-C classes,
1409 and ``-respondsToSelector:`` or ``+instancesRespondToSelector:`` for
1410 Objective-C methods. If such a check was missed, the program would compile
1411 fine, run fine on newer systems, but crash on older systems.
1413 As of LLVM 5.0, ``-Wunguarded-availability`` uses the `availability attributes
1414 <http://clang.llvm.org/docs/AttributeReference.html#availability>`_ together
1415 with the new ``@available()`` keyword to assist with this issue.
1416 When a method that's introduced in the OS newer than the target OS is called, a
1417 -Wunguarded-availability warning is emitted if that call is not guarded:
1419 .. code-block:: objc
1421 void my_fun(NSSomeClass* var) {
1422 // If fancyNewMethod was added in e.g. macOS 10.12, but the code is
1423 // built with -mmacosx-version-min=10.11, then this unconditional call
1424 // will emit a -Wunguarded-availability warning:
1425 [var fancyNewMethod];
1428 To fix the warning and to avoid the crash on macOS 10.11, wrap it in
1429 ``if(@available())``:
1431 .. code-block:: objc
1433 void my_fun(NSSomeClass* var) {
1434 if (@available(macOS 10.12, *)) {
1435 [var fancyNewMethod];
1437 // Put fallback behavior for old macOS versions (and for non-mac
1442 The ``*`` is required and means that platforms not explicitly listed will take
1443 the true branch, and the compiler will emit ``-Wunguarded-availability``
1444 warnings for unlisted platforms based on those platform's deployment target.
1445 More than one platform can be listed in ``@available()``:
1447 .. code-block:: objc
1449 void my_fun(NSSomeClass* var) {
1450 if (@available(macOS 10.12, iOS 10, *)) {
1451 [var fancyNewMethod];
1455 If the caller of ``my_fun()`` already checks that ``my_fun()`` is only called
1456 on 10.12, then add an `availability attribute
1457 <http://clang.llvm.org/docs/AttributeReference.html#availability>`_ to it,
1458 which will also suppress the warning and require that calls to my_fun() are
1461 .. code-block:: objc
1463 API_AVAILABLE(macos(10.12)) void my_fun(NSSomeClass* var) {
1464 [var fancyNewMethod]; // Now ok.
1467 ``@available()`` is only available in Objective-C code. To use the feature
1468 in C and C++ code, use the ``__builtin_available()`` spelling instead.
1470 If existing code uses null checks or ``-respondsToSelector:``, it should
1471 be changed to use ``@available()`` (or ``__builtin_available``) instead.
1473 ``-Wunguarded-availability`` is disabled by default, but
1474 ``-Wunguarded-availability-new``, which only emits this warning for APIs
1475 that have been introduced in macOS >= 10.13, iOS >= 11, watchOS >= 4 and
1476 tvOS >= 11, is enabled by default.
1478 .. _langext-overloading:
1480 Objective-C++ ABI: protocol-qualifier mangling of parameters
1481 ------------------------------------------------------------
1483 Starting with LLVM 3.4, Clang produces a new mangling for parameters whose
1484 type is a qualified-``id`` (e.g., ``id<Foo>``). This mangling allows such
1485 parameters to be differentiated from those with the regular unqualified ``id``
1488 This was a non-backward compatible mangling change to the ABI. This change
1489 allows proper overloading, and also prevents mangling conflicts with template
1490 parameters of protocol-qualified type.
1492 Query the presence of this new mangling with
1493 ``__has_feature(objc_protocol_qualifier_mangling)``.
1495 Initializer lists for complex numbers in C
1496 ==========================================
1498 clang supports an extension which allows the following in C:
1503 #include <complex.h>
1504 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf)
1506 This construct is useful because there is no way to separately initialize the
1507 real and imaginary parts of a complex variable in standard C, given that clang
1508 does not support ``_Imaginary``. (Clang also supports the ``__real__`` and
1509 ``__imag__`` extensions from gcc, which help in some cases, but are not usable
1510 in static initializers.)
1512 Note that this extension does not allow eliding the braces; the meaning of the
1513 following two lines is different:
1517 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1)
1518 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0)
1520 This extension also works in C++ mode, as far as that goes, but does not apply
1521 to the C++ ``std::complex``. (In C++11, list initialization allows the same
1522 syntax to be used with ``std::complex`` with the same meaning.)
1527 Clang supports a number of builtin library functions with the same syntax as
1528 GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``,
1529 ``__builtin_choose_expr``, ``__builtin_types_compatible_p``,
1530 ``__builtin_assume_aligned``, ``__sync_fetch_and_add``, etc. In addition to
1531 the GCC builtins, Clang supports a number of builtins that GCC does not, which
1534 Please note that Clang does not and will not support all of the GCC builtins
1535 for vector operations. Instead of using builtins, you should use the functions
1536 defined in target-specific header files like ``<xmmintrin.h>``, which define
1537 portable wrappers for these. Many of the Clang versions of these functions are
1538 implemented directly in terms of :ref:`extended vector support
1539 <langext-vectors>` instead of builtins, in order to reduce the number of
1540 builtins that we need to implement.
1542 ``__builtin_assume``
1543 ------------------------------
1545 ``__builtin_assume`` is used to provide the optimizer with a boolean
1546 invariant that is defined to be true.
1552 __builtin_assume(bool)
1559 __builtin_assume(x != 0);
1561 // The optimizer may short-circuit this check using the invariant.
1563 return do_something();
1565 return do_something_else();
1570 The boolean argument to this function is defined to be true. The optimizer may
1571 analyze the form of the expression provided as the argument and deduce from
1572 that information used to optimize the program. If the condition is violated
1573 during execution, the behavior is undefined. The argument itself is never
1574 evaluated, so any side effects of the expression will be discarded.
1576 Query for this feature with ``__has_builtin(__builtin_assume)``.
1578 ``__builtin_readcyclecounter``
1579 ------------------------------
1581 ``__builtin_readcyclecounter`` is used to access the cycle counter register (or
1582 a similar low-latency, high-accuracy clock) on those targets that support it.
1588 __builtin_readcyclecounter()
1594 unsigned long long t0 = __builtin_readcyclecounter();
1596 unsigned long long t1 = __builtin_readcyclecounter();
1597 unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow
1601 The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value,
1602 which may be either global or process/thread-specific depending on the target.
1603 As the backing counters often overflow quickly (on the order of seconds) this
1604 should only be used for timing small intervals. When not supported by the
1605 target, the return value is always zero. This builtin takes no arguments and
1606 produces an unsigned long long result.
1608 Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``. Note
1609 that even if present, its use may depend on run-time privilege or other OS
1612 .. _langext-__builtin_shufflevector:
1614 ``__builtin_shufflevector``
1615 ---------------------------
1617 ``__builtin_shufflevector`` is used to express generic vector
1618 permutation/shuffle/swizzle operations. This builtin is also very important
1619 for the implementation of various target-specific header files like
1626 __builtin_shufflevector(vec1, vec2, index1, index2, ...)
1632 // identity operation - return 4-element vector v1.
1633 __builtin_shufflevector(v1, v1, 0, 1, 2, 3)
1635 // "Splat" element 0 of V1 into a 4-element result.
1636 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
1638 // Reverse 4-element vector V1.
1639 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
1641 // Concatenate every other element of 4-element vectors V1 and V2.
1642 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
1644 // Concatenate every other element of 8-element vectors V1 and V2.
1645 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
1647 // Shuffle v1 with some elements being undefined
1648 __builtin_shufflevector(v1, v1, 3, -1, 1, -1)
1652 The first two arguments to ``__builtin_shufflevector`` are vectors that have
1653 the same element type. The remaining arguments are a list of integers that
1654 specify the elements indices of the first two vectors that should be extracted
1655 and returned in a new vector. These element indices are numbered sequentially
1656 starting with the first vector, continuing into the second vector. Thus, if
1657 ``vec1`` is a 4-element vector, index 5 would refer to the second element of
1658 ``vec2``. An index of -1 can be used to indicate that the corresponding element
1659 in the returned vector is a don't care and can be optimized by the backend.
1661 The result of ``__builtin_shufflevector`` is a vector with the same element
1662 type as ``vec1``/``vec2`` but that has an element count equal to the number of
1665 Query for this feature with ``__has_builtin(__builtin_shufflevector)``.
1667 .. _langext-__builtin_convertvector:
1669 ``__builtin_convertvector``
1670 ---------------------------
1672 ``__builtin_convertvector`` is used to express generic vector
1673 type-conversion operations. The input vector and the output vector
1674 type must have the same number of elements.
1680 __builtin_convertvector(src_vec, dst_vec_type)
1686 typedef double vector4double __attribute__((__vector_size__(32)));
1687 typedef float vector4float __attribute__((__vector_size__(16)));
1688 typedef short vector4short __attribute__((__vector_size__(8)));
1689 vector4float vf; vector4short vs;
1691 // convert from a vector of 4 floats to a vector of 4 doubles.
1692 __builtin_convertvector(vf, vector4double)
1694 (vector4double) { (double) vf[0], (double) vf[1], (double) vf[2], (double) vf[3] }
1696 // convert from a vector of 4 shorts to a vector of 4 floats.
1697 __builtin_convertvector(vs, vector4float)
1699 (vector4float) { (float) vs[0], (float) vs[1], (float) vs[2], (float) vs[3] }
1703 The first argument to ``__builtin_convertvector`` is a vector, and the second
1704 argument is a vector type with the same number of elements as the first
1707 The result of ``__builtin_convertvector`` is a vector with the same element
1708 type as the second argument, with a value defined in terms of the action of a
1709 C-style cast applied to each element of the first argument.
1711 Query for this feature with ``__has_builtin(__builtin_convertvector)``.
1713 ``__builtin_bitreverse``
1714 ------------------------
1716 * ``__builtin_bitreverse8``
1717 * ``__builtin_bitreverse16``
1718 * ``__builtin_bitreverse32``
1719 * ``__builtin_bitreverse64``
1725 __builtin_bitreverse32(x)
1731 uint8_t rev_x = __builtin_bitreverse8(x);
1732 uint16_t rev_x = __builtin_bitreverse16(x);
1733 uint32_t rev_y = __builtin_bitreverse32(y);
1734 uint64_t rev_z = __builtin_bitreverse64(z);
1738 The '``__builtin_bitreverse``' family of builtins is used to reverse
1739 the bitpattern of an integer value; for example ``0b10110110`` becomes
1742 ``__builtin_unreachable``
1743 -------------------------
1745 ``__builtin_unreachable`` is used to indicate that a specific point in the
1746 program cannot be reached, even if the compiler might otherwise think it can.
1747 This is useful to improve optimization and eliminates certain warnings. For
1748 example, without the ``__builtin_unreachable`` in the example below, the
1749 compiler assumes that the inline asm can fall through and prints a "function
1750 declared '``noreturn``' should not return" warning.
1756 __builtin_unreachable()
1762 void myabort(void) __attribute__((noreturn));
1763 void myabort(void) {
1765 __builtin_unreachable();
1770 The ``__builtin_unreachable()`` builtin has completely undefined behavior.
1771 Since it has undefined behavior, it is a statement that it is never reached and
1772 the optimizer can take advantage of this to produce better code. This builtin
1773 takes no arguments and produces a void result.
1775 Query for this feature with ``__has_builtin(__builtin_unreachable)``.
1777 ``__builtin_unpredictable``
1778 ---------------------------
1780 ``__builtin_unpredictable`` is used to indicate that a branch condition is
1781 unpredictable by hardware mechanisms such as branch prediction logic.
1787 __builtin_unpredictable(long long)
1793 if (__builtin_unpredictable(x > 0)) {
1799 The ``__builtin_unpredictable()`` builtin is expected to be used with control
1800 flow conditions such as in ``if`` and ``switch`` statements.
1802 Query for this feature with ``__has_builtin(__builtin_unpredictable)``.
1807 ``__sync_swap`` is used to atomically swap integers or pointers in memory.
1813 type __sync_swap(type *ptr, type value, ...)
1819 int old_value = __sync_swap(&value, new_value);
1823 The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of
1824 atomic intrinsics to allow code to atomically swap the current value with the
1825 new value. More importantly, it helps developers write more efficient and
1826 correct code by avoiding expensive loops around
1827 ``__sync_bool_compare_and_swap()`` or relying on the platform specific
1828 implementation details of ``__sync_lock_test_and_set()``. The
1829 ``__sync_swap()`` builtin is a full barrier.
1831 ``__builtin_addressof``
1832 -----------------------
1834 ``__builtin_addressof`` performs the functionality of the built-in ``&``
1835 operator, ignoring any ``operator&`` overload. This is useful in constant
1836 expressions in C++11, where there is no other way to take the address of an
1837 object that overloads ``operator&``.
1843 template<typename T> constexpr T *addressof(T &value) {
1844 return __builtin_addressof(value);
1847 ``__builtin_operator_new`` and ``__builtin_operator_delete``
1848 ------------------------------------------------------------
1850 ``__builtin_operator_new`` allocates memory just like a non-placement non-class
1851 *new-expression*. This is exactly like directly calling the normal
1852 non-placement ``::operator new``, except that it allows certain optimizations
1853 that the C++ standard does not permit for a direct function call to
1854 ``::operator new`` (in particular, removing ``new`` / ``delete`` pairs and
1855 merging allocations).
1857 Likewise, ``__builtin_operator_delete`` deallocates memory just like a
1858 non-class *delete-expression*, and is exactly like directly calling the normal
1859 ``::operator delete``, except that it permits optimizations. Only the unsized
1860 form of ``__builtin_operator_delete`` is currently available.
1862 These builtins are intended for use in the implementation of ``std::allocator``
1863 and other similar allocation libraries, and are only available in C++.
1865 Multiprecision Arithmetic Builtins
1866 ----------------------------------
1868 Clang provides a set of builtins which expose multiprecision arithmetic in a
1869 manner amenable to C. They all have the following form:
1873 unsigned x = ..., y = ..., carryin = ..., carryout;
1874 unsigned sum = __builtin_addc(x, y, carryin, &carryout);
1876 Thus one can form a multiprecision addition chain in the following manner:
1880 unsigned *x, *y, *z, carryin=0, carryout;
1881 z[0] = __builtin_addc(x[0], y[0], carryin, &carryout);
1883 z[1] = __builtin_addc(x[1], y[1], carryin, &carryout);
1885 z[2] = __builtin_addc(x[2], y[2], carryin, &carryout);
1887 z[3] = __builtin_addc(x[3], y[3], carryin, &carryout);
1889 The complete list of builtins are:
1893 unsigned char __builtin_addcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout);
1894 unsigned short __builtin_addcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout);
1895 unsigned __builtin_addc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout);
1896 unsigned long __builtin_addcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout);
1897 unsigned long long __builtin_addcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout);
1898 unsigned char __builtin_subcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout);
1899 unsigned short __builtin_subcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout);
1900 unsigned __builtin_subc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout);
1901 unsigned long __builtin_subcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout);
1902 unsigned long long __builtin_subcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout);
1904 Checked Arithmetic Builtins
1905 ---------------------------
1907 Clang provides a set of builtins that implement checked arithmetic for security
1908 critical applications in a manner that is fast and easily expressable in C. As
1909 an example of their usage:
1913 errorcode_t security_critical_application(...) {
1914 unsigned x, y, result;
1916 if (__builtin_mul_overflow(x, y, &result))
1917 return kErrorCodeHackers;
1919 use_multiply(result);
1923 Clang provides the following checked arithmetic builtins:
1927 bool __builtin_add_overflow (type1 x, type2 y, type3 *sum);
1928 bool __builtin_sub_overflow (type1 x, type2 y, type3 *diff);
1929 bool __builtin_mul_overflow (type1 x, type2 y, type3 *prod);
1930 bool __builtin_uadd_overflow (unsigned x, unsigned y, unsigned *sum);
1931 bool __builtin_uaddl_overflow (unsigned long x, unsigned long y, unsigned long *sum);
1932 bool __builtin_uaddll_overflow(unsigned long long x, unsigned long long y, unsigned long long *sum);
1933 bool __builtin_usub_overflow (unsigned x, unsigned y, unsigned *diff);
1934 bool __builtin_usubl_overflow (unsigned long x, unsigned long y, unsigned long *diff);
1935 bool __builtin_usubll_overflow(unsigned long long x, unsigned long long y, unsigned long long *diff);
1936 bool __builtin_umul_overflow (unsigned x, unsigned y, unsigned *prod);
1937 bool __builtin_umull_overflow (unsigned long x, unsigned long y, unsigned long *prod);
1938 bool __builtin_umulll_overflow(unsigned long long x, unsigned long long y, unsigned long long *prod);
1939 bool __builtin_sadd_overflow (int x, int y, int *sum);
1940 bool __builtin_saddl_overflow (long x, long y, long *sum);
1941 bool __builtin_saddll_overflow(long long x, long long y, long long *sum);
1942 bool __builtin_ssub_overflow (int x, int y, int *diff);
1943 bool __builtin_ssubl_overflow (long x, long y, long *diff);
1944 bool __builtin_ssubll_overflow(long long x, long long y, long long *diff);
1945 bool __builtin_smul_overflow (int x, int y, int *prod);
1946 bool __builtin_smull_overflow (long x, long y, long *prod);
1947 bool __builtin_smulll_overflow(long long x, long long y, long long *prod);
1949 Each builtin performs the specified mathematical operation on the
1950 first two arguments and stores the result in the third argument. If
1951 possible, the result will be equal to mathematically-correct result
1952 and the builtin will return 0. Otherwise, the builtin will return
1953 1 and the result will be equal to the unique value that is equivalent
1954 to the mathematically-correct result modulo two raised to the *k*
1955 power, where *k* is the number of bits in the result type. The
1956 behavior of these builtins is well-defined for all argument values.
1958 The first three builtins work generically for operands of any integer type,
1959 including boolean types. The operands need not have the same type as each
1960 other, or as the result. The other builtins may implicitly promote or
1961 convert their operands before performing the operation.
1963 Query for this feature with ``__has_builtin(__builtin_add_overflow)``, etc.
1965 Floating point builtins
1966 ---------------------------------------
1968 ``__builtin_canonicalize``
1969 --------------------------
1973 double __builtin_canonicalize(double);
1974 float __builtin_canonicalizef(float);
1975 long double__builtin_canonicalizel(long double);
1977 Returns the platform specific canonical encoding of a floating point
1978 number. This canonicalization is useful for implementing certain
1979 numeric primitives such as frexp. See `LLVM canonicalize intrinsic
1980 <http://llvm.org/docs/LangRef.html#llvm-canonicalize-intrinsic>`_ for
1981 more information on the semantics.
1986 Clang provides constant expression evaluation support for builtins forms of
1987 the following functions from the C standard library ``<string.h>`` header:
2002 In each case, the builtin form has the name of the C library function prefixed
2003 by ``__builtin_``. Example:
2007 void *p = __builtin_memchr("foobar", 'b', 5);
2009 In addition to the above, one further builtin is provided:
2013 char *__builtin_char_memchr(const char *haystack, int needle, size_t size);
2015 ``__builtin_char_memchr(a, b, c)`` is identical to
2016 ``(char*)__builtin_memchr(a, b, c)`` except that its use is permitted within
2017 constant expressions in C++11 onwards (where a cast from ``void*`` to ``char*``
2018 is disallowed in general).
2020 Support for constant expression evaluation for the above builtins be detected
2021 with ``__has_feature(cxx_constexpr_string_builtins)``.
2023 Atomic Min/Max builtins with memory ordering
2024 --------------------------------------------
2026 There are two atomic builtins with min/max in-memory comparison and swap.
2027 The syntax and semantics are similar to GCC-compatible __atomic_* builtins.
2029 * ``__atomic_fetch_min``
2030 * ``__atomic_fetch_max``
2032 The builtins work with signed and unsigned integers and require to specify memory ordering.
2033 The return value is the original value that was stored in memory before comparison.
2039 unsigned int val = __atomic_fetch_min(unsigned int *pi, unsigned int ui, __ATOMIC_RELAXED);
2041 The third argument is one of the memory ordering specifiers ``__ATOMIC_RELAXED``,
2042 ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``, ``__ATOMIC_RELEASE``,
2043 ``__ATOMIC_ACQ_REL``, or ``__ATOMIC_SEQ_CST`` following C++11 memory model semantics.
2045 In terms or aquire-release ordering barriers these two operations are always
2046 considered as operations with *load-store* semantics, even when the original value
2047 is not actually modified after comparison.
2049 .. _langext-__c11_atomic:
2051 __c11_atomic builtins
2052 ---------------------
2054 Clang provides a set of builtins which are intended to be used to implement
2055 C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the
2056 ``_explicit`` form of the corresponding C11 operation, and are named with a
2057 ``__c11_`` prefix. The supported operations, and the differences from
2058 the corresponding C11 operations, are:
2060 * ``__c11_atomic_init``
2061 * ``__c11_atomic_thread_fence``
2062 * ``__c11_atomic_signal_fence``
2063 * ``__c11_atomic_is_lock_free`` (The argument is the size of the
2064 ``_Atomic(...)`` object, instead of its address)
2065 * ``__c11_atomic_store``
2066 * ``__c11_atomic_load``
2067 * ``__c11_atomic_exchange``
2068 * ``__c11_atomic_compare_exchange_strong``
2069 * ``__c11_atomic_compare_exchange_weak``
2070 * ``__c11_atomic_fetch_add``
2071 * ``__c11_atomic_fetch_sub``
2072 * ``__c11_atomic_fetch_and``
2073 * ``__c11_atomic_fetch_or``
2074 * ``__c11_atomic_fetch_xor``
2076 The macros ``__ATOMIC_RELAXED``, ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``,
2077 ``__ATOMIC_RELEASE``, ``__ATOMIC_ACQ_REL``, and ``__ATOMIC_SEQ_CST`` are
2078 provided, with values corresponding to the enumerators of C11's
2079 ``memory_order`` enumeration.
2081 (Note that Clang additionally provides GCC-compatible ``__atomic_*``
2082 builtins and OpenCL 2.0 ``__opencl_atomic_*`` builtins. The OpenCL 2.0
2083 atomic builtins are an explicit form of the corresponding OpenCL 2.0
2084 builtin function, and are named with a ``__opencl_`` prefix. The macros
2085 ``__OPENCL_MEMORY_SCOPE_WORK_ITEM``, ``__OPENCL_MEMORY_SCOPE_WORK_GROUP``,
2086 ``__OPENCL_MEMORY_SCOPE_DEVICE``, ``__OPENCL_MEMORY_SCOPE_ALL_SVM_DEVICES``,
2087 and ``__OPENCL_MEMORY_SCOPE_SUB_GROUP`` are provided, with values
2088 corresponding to the enumerators of OpenCL's ``memory_scope`` enumeration.)
2090 Low-level ARM exclusive memory builtins
2091 ---------------------------------------
2093 Clang provides overloaded builtins giving direct access to the three key ARM
2094 instructions for implementing atomic operations.
2098 T __builtin_arm_ldrex(const volatile T *addr);
2099 T __builtin_arm_ldaex(const volatile T *addr);
2100 int __builtin_arm_strex(T val, volatile T *addr);
2101 int __builtin_arm_stlex(T val, volatile T *addr);
2102 void __builtin_arm_clrex(void);
2104 The types ``T`` currently supported are:
2106 * Integer types with width at most 64 bits (or 128 bits on AArch64).
2107 * Floating-point types
2110 Note that the compiler does not guarantee it will not insert stores which clear
2111 the exclusive monitor in between an ``ldrex`` type operation and its paired
2112 ``strex``. In practice this is only usually a risk when the extra store is on
2113 the same cache line as the variable being modified and Clang will only insert
2114 stack stores on its own, so it is best not to use these operations on variables
2115 with automatic storage duration.
2117 Also, loads and stores may be implicit in code written between the ``ldrex`` and
2118 ``strex``. Clang will not necessarily mitigate the effects of these either, so
2119 care should be exercised.
2121 For these reasons the higher level atomic primitives should be preferred where
2124 Non-temporal load/store builtins
2125 --------------------------------
2127 Clang provides overloaded builtins allowing generation of non-temporal memory
2132 T __builtin_nontemporal_load(T *addr);
2133 void __builtin_nontemporal_store(T value, T *addr);
2135 The types ``T`` currently supported are:
2138 * Floating-point types.
2141 Note that the compiler does not guarantee that non-temporal loads or stores
2144 C++ Coroutines support builtins
2145 --------------------------------
2148 This is a work in progress. Compatibility across Clang/LLVM releases is not
2151 Clang provides experimental builtins to support C++ Coroutines as defined by
2152 http://wg21.link/P0057. The following four are intended to be used by the
2153 standard library to implement `std::experimental::coroutine_handle` type.
2159 void __builtin_coro_resume(void *addr);
2160 void __builtin_coro_destroy(void *addr);
2161 bool __builtin_coro_done(void *addr);
2162 void *__builtin_coro_promise(void *addr, int alignment, bool from_promise)
2168 template <> struct coroutine_handle<void> {
2169 void resume() const { __builtin_coro_resume(ptr); }
2170 void destroy() const { __builtin_coro_destroy(ptr); }
2171 bool done() const { return __builtin_coro_done(ptr); }
2177 template <typename Promise> struct coroutine_handle : coroutine_handle<> {
2179 Promise &promise() const {
2180 return *reinterpret_cast<Promise *>(
2181 __builtin_coro_promise(ptr, alignof(Promise), /*from-promise=*/false));
2183 static coroutine_handle from_promise(Promise &promise) {
2185 p.ptr = __builtin_coro_promise(&promise, alignof(Promise),
2186 /*from-promise=*/true);
2192 Other coroutine builtins are either for internal clang use or for use during
2193 development of the coroutine feature. See `Coroutines in LLVM
2194 <http://llvm.org/docs/Coroutines.html#intrinsics>`_ for
2195 more information on their semantics. Note that builtins matching the intrinsics
2196 that take token as the first parameter (llvm.coro.begin, llvm.coro.alloc,
2197 llvm.coro.free and llvm.coro.suspend) omit the token parameter and fill it to
2198 an appropriate value during the emission.
2204 size_t __builtin_coro_size()
2205 void *__builtin_coro_frame()
2206 void *__builtin_coro_free(void *coro_frame)
2208 void *__builtin_coro_id(int align, void *promise, void *fnaddr, void *parts)
2209 bool __builtin_coro_alloc()
2210 void *__builtin_coro_begin(void *memory)
2211 void __builtin_coro_end(void *coro_frame, bool unwind)
2212 char __builtin_coro_suspend(bool final)
2213 bool __builtin_coro_param(void *original, void *copy)
2215 Note that there is no builtin matching the `llvm.coro.save` intrinsic. LLVM
2216 automatically will insert one if the first argument to `llvm.coro.suspend` is
2217 token `none`. If a user calls `__builin_suspend`, clang will insert `token none`
2218 as the first argument to the intrinsic.
2220 Non-standard C++11 Attributes
2221 =============================
2223 Clang's non-standard C++11 attributes live in the ``clang`` attribute
2226 Clang supports GCC's ``gnu`` attribute namespace. All GCC attributes which
2227 are accepted with the ``__attribute__((foo))`` syntax are also accepted as
2228 ``[[gnu::foo]]``. This only extends to attributes which are specified by GCC
2229 (see the list of `GCC function attributes
2230 <http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_, `GCC variable
2231 attributes <http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html>`_, and
2232 `GCC type attributes
2233 <http://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html>`_). As with the GCC
2234 implementation, these attributes must appertain to the *declarator-id* in a
2235 declaration, which means they must go either at the start of the declaration or
2236 immediately after the name being declared.
2238 For example, this applies the GNU ``unused`` attribute to ``a`` and ``f``, and
2239 also applies the GNU ``noreturn`` attribute to ``f``.
2243 [[gnu::unused]] int a, f [[gnu::noreturn]] ();
2245 Target-Specific Extensions
2246 ==========================
2248 Clang supports some language features conditionally on some targets.
2250 ARM/AArch64 Language Extensions
2251 -------------------------------
2253 Memory Barrier Intrinsics
2254 ^^^^^^^^^^^^^^^^^^^^^^^^^
2255 Clang implements the ``__dmb``, ``__dsb`` and ``__isb`` intrinsics as defined
2256 in the `ARM C Language Extensions Release 2.0
2257 <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_.
2258 Note that these intrinsics are implemented as motion barriers that block
2259 reordering of memory accesses and side effect instructions. Other instructions
2260 like simple arithmetic may be reordered around the intrinsic. If you expect to
2261 have no reordering at all, use inline assembly instead.
2263 X86/X86-64 Language Extensions
2264 ------------------------------
2266 The X86 backend has these language extensions:
2268 Memory references to specified segments
2269 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2271 Annotating a pointer with address space #256 causes it to be code generated
2272 relative to the X86 GS segment register, address space #257 causes it to be
2273 relative to the X86 FS segment, and address space #258 causes it to be
2274 relative to the X86 SS segment. Note that this is a very very low-level
2275 feature that should only be used if you know what you're doing (for example in
2282 #define GS_RELATIVE __attribute__((address_space(256)))
2283 int foo(int GS_RELATIVE *P) {
2287 Which compiles to (on X86-32):
2293 movl %gs:(%eax), %eax
2296 Extensions for Static Analysis
2297 ==============================
2299 Clang supports additional attributes that are useful for documenting program
2300 invariants and rules for static analysis tools, such as the `Clang Static
2301 Analyzer <http://clang-analyzer.llvm.org/>`_. These attributes are documented
2302 in the analyzer's `list of source-level annotations
2303 <http://clang-analyzer.llvm.org/annotations.html>`_.
2306 Extensions for Dynamic Analysis
2307 ===============================
2309 Use ``__has_feature(address_sanitizer)`` to check if the code is being built
2310 with :doc:`AddressSanitizer`.
2312 Use ``__has_feature(thread_sanitizer)`` to check if the code is being built
2313 with :doc:`ThreadSanitizer`.
2315 Use ``__has_feature(memory_sanitizer)`` to check if the code is being built
2316 with :doc:`MemorySanitizer`.
2318 Use ``__has_feature(safe_stack)`` to check if the code is being built
2319 with :doc:`SafeStack`.
2322 Extensions for selectively disabling optimization
2323 =================================================
2325 Clang provides a mechanism for selectively disabling optimizations in functions
2328 To disable optimizations in a single function definition, the GNU-style or C++11
2329 non-standard attribute ``optnone`` can be used.
2333 // The following functions will not be optimized.
2334 // GNU-style attribute
2335 __attribute__((optnone)) int foo() {
2339 [[clang::optnone]] int bar() {
2343 To facilitate disabling optimization for a range of function definitions, a
2344 range-based pragma is provided. Its syntax is ``#pragma clang optimize``
2345 followed by ``off`` or ``on``.
2347 All function definitions in the region between an ``off`` and the following
2348 ``on`` will be decorated with the ``optnone`` attribute unless doing so would
2349 conflict with explicit attributes already present on the function (e.g. the
2350 ones that control inlining).
2354 #pragma clang optimize off
2355 // This function will be decorated with optnone.
2360 // optnone conflicts with always_inline, so bar() will not be decorated.
2361 __attribute__((always_inline)) int bar() {
2364 #pragma clang optimize on
2366 If no ``on`` is found to close an ``off`` region, the end of the region is the
2367 end of the compilation unit.
2369 Note that a stray ``#pragma clang optimize on`` does not selectively enable
2370 additional optimizations when compiling at low optimization levels. This feature
2371 can only be used to selectively disable optimizations.
2373 The pragma has an effect on functions only at the point of their definition; for
2374 function templates, this means that the state of the pragma at the point of an
2375 instantiation is not necessarily relevant. Consider the following example:
2379 template<typename T> T twice(T t) {
2383 #pragma clang optimize off
2384 template<typename T> T thrice(T t) {
2388 int container(int a, int b) {
2389 return twice(a) + thrice(b);
2391 #pragma clang optimize on
2393 In this example, the definition of the template function ``twice`` is outside
2394 the pragma region, whereas the definition of ``thrice`` is inside the region.
2395 The ``container`` function is also in the region and will not be optimized, but
2396 it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of
2397 these two instantiations, ``twice`` will be optimized (because its definition
2398 was outside the region) and ``thrice`` will not be optimized.
2400 Extensions for loop hint optimizations
2401 ======================================
2403 The ``#pragma clang loop`` directive is used to specify hints for optimizing the
2404 subsequent for, while, do-while, or c++11 range-based for loop. The directive
2405 provides options for vectorization, interleaving, unrolling and
2406 distribution. Loop hints can be specified before any loop and will be ignored if
2407 the optimization is not safe to apply.
2409 Vectorization and Interleaving
2410 ------------------------------
2412 A vectorized loop performs multiple iterations of the original loop
2413 in parallel using vector instructions. The instruction set of the target
2414 processor determines which vector instructions are available and their vector
2415 widths. This restricts the types of loops that can be vectorized. The vectorizer
2416 automatically determines if the loop is safe and profitable to vectorize. A
2417 vector instruction cost model is used to select the vector width.
2419 Interleaving multiple loop iterations allows modern processors to further
2420 improve instruction-level parallelism (ILP) using advanced hardware features,
2421 such as multiple execution units and out-of-order execution. The vectorizer uses
2422 a cost model that depends on the register pressure and generated code size to
2423 select the interleaving count.
2425 Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled
2426 by ``interleave(enable)``. This is useful when compiling with ``-Os`` to
2427 manually enable vectorization or interleaving.
2431 #pragma clang loop vectorize(enable)
2432 #pragma clang loop interleave(enable)
2437 The vector width is specified by ``vectorize_width(_value_)`` and the interleave
2438 count is specified by ``interleave_count(_value_)``, where
2439 _value_ is a positive integer. This is useful for specifying the optimal
2440 width/count of the set of target architectures supported by your application.
2444 #pragma clang loop vectorize_width(2)
2445 #pragma clang loop interleave_count(2)
2450 Specifying a width/count of 1 disables the optimization, and is equivalent to
2451 ``vectorize(disable)`` or ``interleave(disable)``.
2456 Unrolling a loop reduces the loop control overhead and exposes more
2457 opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling
2458 eliminates the loop and replaces it with an enumerated sequence of loop
2459 iterations. Full unrolling is only possible if the loop trip count is known at
2460 compile time. Partial unrolling replicates the loop body within the loop and
2461 reduces the trip count.
2463 If ``unroll(enable)`` is specified the unroller will attempt to fully unroll the
2464 loop if the trip count is known at compile time. If the fully unrolled code size
2465 is greater than an internal limit the loop will be partially unrolled up to this
2466 limit. If the trip count is not known at compile time the loop will be partially
2467 unrolled with a heuristically chosen unroll factor.
2471 #pragma clang loop unroll(enable)
2476 If ``unroll(full)`` is specified the unroller will attempt to fully unroll the
2477 loop if the trip count is known at compile time identically to
2478 ``unroll(enable)``. However, with ``unroll(full)`` the loop will not be unrolled
2479 if the loop count is not known at compile time.
2483 #pragma clang loop unroll(full)
2488 The unroll count can be specified explicitly with ``unroll_count(_value_)`` where
2489 _value_ is a positive integer. If this value is greater than the trip count the
2490 loop will be fully unrolled. Otherwise the loop is partially unrolled subject
2491 to the same code size limit as with ``unroll(enable)``.
2495 #pragma clang loop unroll_count(8)
2500 Unrolling of a loop can be prevented by specifying ``unroll(disable)``.
2505 Loop Distribution allows splitting a loop into multiple loops. This is
2506 beneficial for example when the entire loop cannot be vectorized but some of the
2507 resulting loops can.
2509 If ``distribute(enable))`` is specified and the loop has memory dependencies
2510 that inhibit vectorization, the compiler will attempt to isolate the offending
2511 operations into a new loop. This optimization is not enabled by default, only
2512 loops marked with the pragma are considered.
2516 #pragma clang loop distribute(enable)
2517 for (i = 0; i < N; ++i) {
2518 S1: A[i + 1] = A[i] + B[i];
2519 S2: C[i] = D[i] * E[i];
2522 This loop will be split into two loops between statements S1 and S2. The
2523 second loop containing S2 will be vectorized.
2525 Loop Distribution is currently not enabled by default in the optimizer because
2526 it can hurt performance in some cases. For example, instruction-level
2527 parallelism could be reduced by sequentializing the execution of the
2528 statements S1 and S2 above.
2530 If Loop Distribution is turned on globally with
2531 ``-mllvm -enable-loop-distribution``, specifying ``distribute(disable)`` can
2532 be used the disable it on a per-loop basis.
2534 Additional Information
2535 ----------------------
2537 For convenience multiple loop hints can be specified on a single line.
2541 #pragma clang loop vectorize_width(4) interleave_count(8)
2546 If an optimization cannot be applied any hints that apply to it will be ignored.
2547 For example, the hint ``vectorize_width(4)`` is ignored if the loop is not
2548 proven safe to vectorize. To identify and diagnose optimization issues use
2549 `-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the
2550 user guide for details.
2552 Extensions to specify floating-point flags
2553 ====================================================
2555 The ``#pragma clang fp`` pragma allows floating-point options to be specified
2556 for a section of the source code. This pragma can only appear at file scope or
2557 at the start of a compound statement (excluding comments). When using within a
2558 compound statement, the pragma is active within the scope of the compound
2561 Currently, only FP contraction can be controlled with the pragma. ``#pragma
2562 clang fp contract`` specifies whether the compiler should contract a multiply
2563 and an addition (or subtraction) into a fused FMA operation when supported by
2566 The pragma can take three values: ``on``, ``fast`` and ``off``. The ``on``
2567 option is identical to using ``#pragma STDC FP_CONTRACT(ON)`` and it allows
2568 fusion as specified the language standard. The ``fast`` option allows fusiong
2569 in cases when the language standard does not make this possible (e.g. across
2575 #pragma clang fp contract(fast)
2581 The pragma can also be used with ``off`` which turns FP contraction off for a
2582 section of the code. This can be useful when fast contraction is otherwise
2583 enabled for the translation unit with the ``-ffp-contract=fast`` flag.
2585 Specifying an attribute for multiple declarations (#pragma clang attribute)
2586 ===========================================================================
2588 The ``#pragma clang attribute`` directive can be used to apply an attribute to
2589 multiple declarations. The ``#pragma clang attribute push`` variation of the
2590 directive pushes a new attribute to the attribute stack. The declarations that
2591 follow the pragma receive the attributes that are on the attribute stack, until
2592 the stack is cleared using a ``#pragma clang attribute pop`` directive. Multiple
2593 push directives can be nested inside each other.
2595 The attributes that are used in the ``#pragma clang attribute`` directives
2596 can be written using the GNU-style syntax:
2600 #pragma clang attribute push(__attribute__((annotate("custom"))), apply_to = function)
2602 void function(); // The function now has the annotate("custom") attribute
2604 #pragma clang attribute pop
2606 The attributes can also be written using the C++11 style syntax:
2610 #pragma clang attribute push([[noreturn]], apply_to = function)
2612 void function(); // The function now has the [[noreturn]] attribute
2614 #pragma clang attribute pop
2616 The ``__declspec`` style syntax is also supported:
2620 #pragma clang attribute push(__declspec(dllexport), apply_to = function)
2622 void function(); // The function now has the __declspec(dllexport) attribute
2624 #pragma clang attribute pop
2626 A single push directive accepts only one attribute regardless of the syntax
2632 The set of declarations that receive a single attribute from the attribute stack
2633 depends on the subject match rules that were specified in the pragma. Subject
2634 match rules are specified after the attribute. The compiler expects an
2635 identifier that corresponds to the subject set specifier. The ``apply_to``
2636 specifier is currently the only supported subject set specifier. It allows you
2637 to specify match rules that form a subset of the attribute's allowed subject
2638 set, i.e. the compiler doesn't require all of the attribute's subjects. For
2639 example, an attribute like ``[[nodiscard]]`` whose subject set includes
2640 ``enum``, ``record`` and ``hasType(functionType)``, requires the presence of at
2641 least one of these rules after ``apply_to``:
2645 #pragma clang attribute push([[nodiscard]], apply_to = enum)
2647 enum Enum1 { A1, B1 }; // The enum will receive [[nodiscard]]
2649 struct Record1 { }; // The struct will *not* receive [[nodiscard]]
2651 #pragma clang attribute pop
2653 #pragma clang attribute push([[nodiscard]], apply_to = any(record, enum))
2655 enum Enum2 { A2, B2 }; // The enum will receive [[nodiscard]]
2657 struct Record2 { }; // The struct *will* receive [[nodiscard]]
2659 #pragma clang attribute pop
2661 // This is an error, since [[nodiscard]] can't be applied to namespaces:
2662 #pragma clang attribute push([[nodiscard]], apply_to = any(record, namespace))
2664 #pragma clang attribute pop
2666 Multiple match rules can be specified using the ``any`` match rule, as shown
2667 in the example above. The ``any`` rule applies attributes to all declarations
2668 that are matched by at least one of the rules in the ``any``. It doesn't nest
2669 and can't be used inside the other match rules. Redundant match rules or rules
2670 that conflict with one another should not be used inside of ``any``.
2672 Clang supports the following match rules:
2674 - ``function``: Can be used to apply attributes to functions. This includes C++
2675 member functions, static functions, operators, and constructors/destructors.
2677 - ``function(is_member)``: Can be used to apply attributes to C++ member
2678 functions. This includes members like static functions, operators, and
2679 constructors/destructors.
2681 - ``hasType(functionType)``: Can be used to apply attributes to functions, C++
2682 member functions, and variables/fields whose type is a function pointer. It
2683 does not apply attributes to Objective-C methods or blocks.
2685 - ``type_alias``: Can be used to apply attributes to ``typedef`` declarations
2686 and C++11 type aliases.
2688 - ``record``: Can be used to apply attributes to ``struct``, ``class``, and
2689 ``union`` declarations.
2691 - ``record(unless(is_union))``: Can be used to apply attributes only to
2692 ``struct`` and ``class`` declarations.
2694 - ``enum``: Can be be used to apply attributes to enumeration declarations.
2696 - ``enum_constant``: Can be used to apply attributes to enumerators.
2698 - ``variable``: Can be used to apply attributes to variables, including
2699 local variables, parameters, global variables, and static member variables.
2700 It does not apply attributes to instance member variables or Objective-C
2703 - ``variable(is_thread_local)``: Can be used to apply attributes to thread-local
2706 - ``variable(is_global)``: Can be used to apply attributes to global variables
2709 - ``variable(is_parameter)``: Can be used to apply attributes to parameters
2712 - ``variable(unless(is_parameter))``: Can be used to apply attributes to all
2713 the variables that are not parameters.
2715 - ``field``: Can be used to apply attributes to non-static member variables
2716 in a record. This includes Objective-C ivars.
2718 - ``namespace``: Can be used to apply attributes to ``namespace`` declarations.
2720 - ``objc_interface``: Can be used to apply attributes to ``@interface``
2723 - ``objc_protocol``: Can be used to apply attributes to ``@protocol``
2726 - ``objc_category``: Can be used to apply attributes to category declarations,
2727 including class extensions.
2729 - ``objc_method``: Can be used to apply attributes to Objective-C methods,
2730 including instance and class methods. Implicit methods like implicit property
2731 getters and setters do not receive the attribute.
2733 - ``objc_method(is_instance)``: Can be used to apply attributes to Objective-C
2736 - ``objc_property``: Can be used to apply attributes to ``@property``
2739 - ``block``: Can be used to apply attributes to block declarations. This does
2740 not include variables/fields of block pointer type.
2742 The use of ``unless`` in match rules is currently restricted to a strict set of
2743 sub-rules that are used by the supported attributes. That means that even though
2744 ``variable(unless(is_parameter))`` is a valid match rule,
2745 ``variable(unless(is_thread_local))`` is not.
2747 Supported Attributes
2748 --------------------
2750 Not all attributes can be used with the ``#pragma clang attribute`` directive.
2751 Notably, statement attributes like ``[[fallthrough]]`` or type attributes
2752 like ``address_space`` aren't supported by this directive. You can determine
2753 whether or not an attribute is supported by the pragma by referring to the
2754 :doc:`individual documentation for that attribute <AttributeReference>`.
2756 The attributes are applied to all matching declarations individually, even when
2757 the attribute is semantically incorrect. The attributes that aren't applied to
2758 any declaration are not verified semantically.
2760 Specifying section names for global objects (#pragma clang section)
2761 ===================================================================
2763 The ``#pragma clang section`` directive provides a means to assign section-names
2764 to global variables, functions and static variables.
2766 The section names can be specified as:
2770 #pragma clang section bss="myBSS" data="myData" rodata="myRodata" text="myText"
2772 The section names can be reverted back to default name by supplying an empty
2773 string to the section kind, for example:
2777 #pragma clang section bss="" data="" text="" rodata=""
2779 The ``#pragma clang section`` directive obeys the following rules:
2781 * The pragma applies to all global variable, statics and function declarations
2782 from the pragma to the end of the translation unit.
2784 * The pragma clang section is enabled automatically, without need of any flags.
2786 * This feature is only defined to work sensibly for ELF targets.
2788 * If section name is specified through _attribute_((section("myname"))), then
2789 the attribute name gains precedence.
2791 * Global variables that are initialized to zero will be placed in the named
2792 bss section, if one is present.
2794 * The ``#pragma clang section`` directive does not does try to infer section-kind
2795 from the name. For example, naming a section "``.bss.mySec``" does NOT mean
2796 it will be a bss section name.
2798 * The decision about which section-kind applies to each global is taken in the back-end.
2799 Once the section-kind is known, appropriate section name, as specified by the user using
2800 ``#pragma clang section`` directive, is applied to that global.
2802 Specifying Linker Options on ELF Targets
2803 ========================================
2805 The ``#pragma comment(lib, ...)`` directive is supported on all ELF targets.
2806 The second parameter is the library name (without the traditional Unix prefix of
2807 ``lib``). This allows you to provide an implicit link of dependent libraries.