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 backwards compatibility reasons, ``__has_feature`` can also be used to test
95 for support for non-standardized features, i.e. features not prefixed ``c_``,
96 ``cxx_`` or ``objc_``.
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``.
115 This function-like macro takes a single identifier argument that is the name of
116 an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It
117 can be used like this:
121 #ifndef __has_attribute // Optional of course.
122 #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
126 #if __has_attribute(always_inline)
127 #define ALWAYS_INLINE __attribute__((always_inline))
129 #define ALWAYS_INLINE
133 The attribute name can also be specified with a preceding and following ``__``
134 (double underscore) to avoid interference from a macro with the same name. For
135 instance, ``__always_inline__`` can be used instead of ``always_inline``.
137 Include File Checking Macros
138 ============================
140 Not all developments systems have the same include files. The
141 :ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow
142 you to check for the existence of an include file before doing a possibly
143 failing ``#include`` directive. Include file checking macros must be used
144 as expressions in ``#if`` or ``#elif`` preprocessing directives.
146 .. _langext-__has_include:
151 This function-like macro takes a single file name string argument that is the
152 name of an include file. It evaluates to 1 if the file can be found using the
153 include paths, or 0 otherwise:
157 // Note the two possible file name string formats.
158 #if __has_include("myinclude.h") && __has_include(<stdint.h>)
159 # include "myinclude.h"
162 // To avoid problem with non-clang compilers not having this macro.
163 #if defined(__has_include) && __has_include("myinclude.h")
164 # include "myinclude.h"
167 To test for this feature, use ``#if defined(__has_include)``.
169 .. _langext-__has_include_next:
171 ``__has_include_next``
172 ----------------------
174 This function-like macro takes a single file name string argument that is the
175 name of an include file. It is like ``__has_include`` except that it looks for
176 the second instance of the given file found in the include paths. It evaluates
177 to 1 if the second instance of the file can be found using the include paths,
182 // Note the two possible file name string formats.
183 #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)
184 # include_next "myinclude.h"
187 // To avoid problem with non-clang compilers not having this macro.
188 #if defined(__has_include_next) && __has_include_next("myinclude.h")
189 # include_next "myinclude.h"
192 Note that ``__has_include_next``, like the GNU extension ``#include_next``
193 directive, is intended for use in headers only, and will issue a warning if
194 used in the top-level compilation file. A warning will also be issued if an
195 absolute path is used in the file argument.
200 This function-like macro takes a string literal that represents a command line
201 option for a warning and returns true if that is a valid warning option.
205 #if __has_warning("-Wformat")
213 Defined to a string that contains the name of the main input file passed to
217 Defined to an integer value that starts at zero and is incremented each time
218 the ``__COUNTER__`` macro is expanded.
220 ``__INCLUDE_LEVEL__``
221 Defined to an integral value that is the include depth of the file currently
222 being translated. For the main file, this value is zero.
225 Defined to the date and time of the last modification of the current source
229 Defined when compiling with Clang
232 Defined to the major marketing version number of Clang (e.g., the 2 in
233 2.0.1). Note that marketing version numbers should not be used to check for
234 language features, as different vendors use different numbering schemes.
235 Instead, use the :ref:`langext-feature_check`.
238 Defined to the minor version number of Clang (e.g., the 0 in 2.0.1). Note
239 that marketing version numbers should not be used to check for language
240 features, as different vendors use different numbering schemes. Instead, use
241 the :ref:`langext-feature_check`.
243 ``__clang_patchlevel__``
244 Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).
246 ``__clang_version__``
247 Defined to a string that captures the Clang marketing version, including the
248 Subversion tag or revision number, e.g., "``1.5 (trunk 102332)``".
252 Vectors and Extended Vectors
253 ============================
255 Supports the GCC, OpenCL, AltiVec and NEON vector extensions.
257 OpenCL vector types are created using ``ext_vector_type`` attribute. It
258 support for ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example
263 typedef float float4 __attribute__((ext_vector_type(4)));
264 typedef float float2 __attribute__((ext_vector_type(2)));
266 float4 foo(float2 a, float2 b) {
273 Query for this feature with ``__has_extension(attribute_ext_vector_type)``.
275 Giving ``-faltivec`` option to clang enables support for AltiVec vector syntax
276 and functions. For example:
280 vector float foo(vector int a) {
282 b = vec_add(a, a) + a;
283 return (vector float)b;
286 NEON vector types are created using ``neon_vector_type`` and
287 ``neon_polyvector_type`` attributes. For example:
291 typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t;
292 typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t;
294 int8x8_t foo(int8x8_t a) {
303 Vector literals can be used to create vectors from a set of scalars, or
304 vectors. Either parentheses or braces form can be used. In the parentheses
305 form the number of literal values specified must be one, i.e. referring to a
306 scalar value, or must match the size of the vector type being created. If a
307 single scalar literal value is specified, the scalar literal value will be
308 replicated to all the components of the vector type. In the brackets form any
309 number of literals can be specified. For example:
313 typedef int v4si __attribute__((__vector_size__(16)));
314 typedef float float4 __attribute__((ext_vector_type(4)));
315 typedef float float2 __attribute__((ext_vector_type(2)));
317 v4si vsi = (v4si){1, 2, 3, 4};
318 float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f);
319 vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1).
320 vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0).
321 vector int vi3 = (vector int)(1, 2); // error
322 vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0).
323 vector int vi5 = (vector int)(1, 2, 3, 4);
324 float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f));
329 The table below shows the support for each operation by vector extension. A
330 dash indicates that an operation is not accepted according to a corresponding
333 ============================== ====== ======= === ====
334 Opeator OpenCL AltiVec GCC NEON
335 ============================== ====== ======= === ====
337 unary operators +, -- yes yes yes --
338 ++, -- -- yes yes yes --
339 +,--,*,/,% yes yes yes --
340 bitwise operators &,|,^,~ yes yes yes --
342 !, &&, || no -- -- --
343 ==, !=, >, <, >=, <= yes yes -- --
346 sizeof yes yes yes yes
347 ============================== ====== ======= === ====
349 See also :ref:`langext-__builtin_shufflevector`.
351 Messages on ``deprecated`` and ``unavailable`` Attributes
352 =========================================================
354 An optional string message can be added to the ``deprecated`` and
355 ``unavailable`` attributes. For example:
359 void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));
361 If the deprecated or unavailable declaration is used, the message will be
362 incorporated into the appropriate diagnostic:
366 harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
367 [-Wdeprecated-declarations]
371 Query for this feature with
372 ``__has_extension(attribute_deprecated_with_message)`` and
373 ``__has_extension(attribute_unavailable_with_message)``.
375 Attributes on Enumerators
376 =========================
378 Clang allows attributes to be written on individual enumerators. This allows
379 enumerators to be deprecated, made unavailable, etc. The attribute must appear
380 after the enumerator name and before any initializer, like so:
387 OM_Terrified __attribute__((deprecated)),
388 OM_AbortOnError __attribute__((deprecated)) = 4
391 Attributes on the ``enum`` declaration do not apply to individual enumerators.
393 Query for this feature with ``__has_extension(enumerator_attributes)``.
395 'User-Specified' System Frameworks
396 ==================================
398 Clang provides a mechanism by which frameworks can be built in such a way that
399 they will always be treated as being "system frameworks", even if they are not
400 present in a system framework directory. This can be useful to system
401 framework developers who want to be able to test building other applications
402 with development builds of their framework, including the manner in which the
403 compiler changes warning behavior for system headers.
405 Framework developers can opt-in to this mechanism by creating a
406 "``.system_framework``" file at the top-level of their framework. That is, the
407 framework should have contents like:
411 .../TestFramework.framework
412 .../TestFramework.framework/.system_framework
413 .../TestFramework.framework/Headers
414 .../TestFramework.framework/Headers/TestFramework.h
417 Clang will treat the presence of this file as an indicator that the framework
418 should be treated as a system framework, regardless of how it was found in the
419 framework search path. For consistency, we recommend that such files never be
420 included in installed versions of the framework.
422 Availability attribute
423 ======================
425 Clang introduces the ``availability`` attribute, which can be placed on
426 declarations to describe the lifecycle of that declaration relative to
427 operating system versions. Consider the function declaration for a
428 hypothetical function ``f``:
432 void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
434 The availability attribute states that ``f`` was introduced in Mac OS X 10.4,
435 deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information
436 is used by Clang to determine when it is safe to use ``f``: for example, if
437 Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``
438 succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call
439 succeeds but Clang emits a warning specifying that the function is deprecated.
440 Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call
441 fails because ``f()`` is no longer available.
443 The availability attribute is a comma-separated list starting with the
444 platform name and then including clauses specifying important milestones in the
445 declaration's lifetime (in any order) along with additional information. Those
448 introduced=\ *version*
449 The first version in which this declaration was introduced.
451 deprecated=\ *version*
452 The first version in which this declaration was deprecated, meaning that
453 users should migrate away from this API.
455 obsoleted=\ *version*
456 The first version in which this declaration was obsoleted, meaning that it
457 was removed completely and can no longer be used.
460 This declaration is never available on this platform.
462 message=\ *string-literal*
463 Additional message text that Clang will provide when emitting a warning or
464 error about use of a deprecated or obsoleted declaration. Useful to direct
465 users to replacement APIs.
467 Multiple availability attributes can be placed on a declaration, which may
468 correspond to different platforms. Only the availability attribute with the
469 platform corresponding to the target platform will be used; any others will be
470 ignored. If no availability attribute specifies availability for the current
471 target platform, the availability attributes are ignored. Supported platforms
475 Apple's iOS operating system. The minimum deployment target is specified by
476 the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*``
477 command-line arguments.
480 Apple's Mac OS X operating system. The minimum deployment target is
481 specified by the ``-mmacosx-version-min=*version*`` command-line argument.
483 A declaration can be used even when deploying back to a platform version prior
484 to when the declaration was introduced. When this happens, the declaration is
486 <https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
487 as if the ``weak_import`` attribute were added to the declaration. A
488 weakly-linked declaration may or may not be present a run-time, and a program
489 can determine whether the declaration is present by checking whether the
490 address of that declaration is non-NULL.
492 If there are multiple declarations of the same entity, the availability
493 attributes must either match on a per-platform basis or later
494 declarations must not have availability attributes for that
495 platform. For example:
499 void g(void) __attribute__((availability(macosx,introduced=10.4)));
500 void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches
501 void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
502 void g(void); // okay, inherits both macosx and ios availability from above.
503 void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch
505 When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
510 - (id)method __attribute__((availability(macosx,introduced=10.4)));
511 - (id)method2 __attribute__((availability(macosx,introduced=10.4)));
515 - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later
516 - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4
519 Checks for Standard Language Features
520 =====================================
522 The ``__has_feature`` macro can be used to query if certain standard language
523 features are enabled. The ``__has_extension`` macro can be used to query if
524 language features are available as an extension when compiling for a standard
525 which does not provide them. The features which can be tested are listed here.
530 The features listed below are part of the C++98 standard. These features are
531 enabled by default when compiling C++ code.
536 Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been
537 enabled. For example, compiling code with ``-fno-exceptions`` disables C++
543 Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For
544 example, compiling code with ``-fno-rtti`` disables the use of RTTI.
549 The features listed below are part of the C++11 standard. As a result, all
550 these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option
551 when compiling C++ code.
553 C++11 SFINAE includes access control
554 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
556 Use ``__has_feature(cxx_access_control_sfinae)`` or
557 ``__has_extension(cxx_access_control_sfinae)`` to determine whether
558 access-control errors (e.g., calling a private constructor) are considered to
559 be template argument deduction errors (aka SFINAE errors), per `C++ DR1170
560 <http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170>`_.
562 C++11 alias templates
563 ^^^^^^^^^^^^^^^^^^^^^
565 Use ``__has_feature(cxx_alias_templates)`` or
566 ``__has_extension(cxx_alias_templates)`` to determine if support for C++11's
567 alias declarations and alias templates is enabled.
569 C++11 alignment specifiers
570 ^^^^^^^^^^^^^^^^^^^^^^^^^^
572 Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to
573 determine if support for alignment specifiers using ``alignas`` is enabled.
578 Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to
579 determine if support for attribute parsing with C++11's square bracket notation
582 C++11 generalized constant expressions
583 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
585 Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized
586 constant expressions (e.g., ``constexpr``) is enabled.
591 Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to
592 determine if support for the ``decltype()`` specifier is enabled. C++11's
593 ``decltype`` does not require type-completeness of a function call expression.
594 Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or
595 ``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if
596 support for this feature is enabled.
598 C++11 default template arguments in function templates
599 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
601 Use ``__has_feature(cxx_default_function_template_args)`` or
602 ``__has_extension(cxx_default_function_template_args)`` to determine if support
603 for default template arguments in function templates is enabled.
605 C++11 ``default``\ ed functions
606 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
608 Use ``__has_feature(cxx_defaulted_functions)`` or
609 ``__has_extension(cxx_defaulted_functions)`` to determine if support for
610 defaulted function definitions (with ``= default``) is enabled.
612 C++11 delegating constructors
613 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
615 Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for
616 delegating constructors is enabled.
618 C++11 ``deleted`` functions
619 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
621 Use ``__has_feature(cxx_deleted_functions)`` or
622 ``__has_extension(cxx_deleted_functions)`` to determine if support for deleted
623 function definitions (with ``= delete``) is enabled.
625 C++11 explicit conversion functions
626 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
628 Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for
629 ``explicit`` conversion functions is enabled.
631 C++11 generalized initializers
632 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
634 Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for
635 generalized initializers (using braced lists and ``std::initializer_list``) is
638 C++11 implicit move constructors/assignment operators
639 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
641 Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly
642 generate move constructors and move assignment operators where needed.
644 C++11 inheriting constructors
645 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
647 Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for
648 inheriting constructors is enabled.
650 C++11 inline namespaces
651 ^^^^^^^^^^^^^^^^^^^^^^^
653 Use ``__has_feature(cxx_inline_namespaces)`` or
654 ``__has_extension(cxx_inline_namespaces)`` to determine if support for inline
655 namespaces is enabled.
660 Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to
661 determine if support for lambdas is enabled.
663 C++11 local and unnamed types as template arguments
664 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
666 Use ``__has_feature(cxx_local_type_template_args)`` or
667 ``__has_extension(cxx_local_type_template_args)`` to determine if support for
668 local and unnamed types as template arguments is enabled.
673 Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to
674 determine if support for noexcept exception specifications is enabled.
676 C++11 in-class non-static data member initialization
677 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
679 Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class
680 initialization of non-static data members is enabled.
685 Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to
686 determine if support for ``nullptr`` is enabled.
688 C++11 ``override control``
689 ^^^^^^^^^^^^^^^^^^^^^^^^^^
691 Use ``__has_feature(cxx_override_control)`` or
692 ``__has_extension(cxx_override_control)`` to determine if support for the
693 override control keywords is enabled.
695 C++11 reference-qualified functions
696 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
698 Use ``__has_feature(cxx_reference_qualified_functions)`` or
699 ``__has_extension(cxx_reference_qualified_functions)`` to determine if support
700 for reference-qualified functions (e.g., member functions with ``&`` or ``&&``
701 applied to ``*this``) is enabled.
703 C++11 range-based ``for`` loop
704 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
706 Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to
707 determine if support for the range-based for loop is enabled.
709 C++11 raw string literals
710 ^^^^^^^^^^^^^^^^^^^^^^^^^
712 Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw
713 string literals (e.g., ``R"x(foo\bar)x"``) is enabled.
715 C++11 rvalue references
716 ^^^^^^^^^^^^^^^^^^^^^^^
718 Use ``__has_feature(cxx_rvalue_references)`` or
719 ``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue
720 references is enabled.
722 C++11 ``static_assert()``
723 ^^^^^^^^^^^^^^^^^^^^^^^^^
725 Use ``__has_feature(cxx_static_assert)`` or
726 ``__has_extension(cxx_static_assert)`` to determine if support for compile-time
727 assertions using ``static_assert`` is enabled.
729 C++11 ``thread_local``
730 ^^^^^^^^^^^^^^^^^^^^^^
732 Use ``__has_feature(cxx_thread_local)`` to determine if support for
733 ``thread_local`` variables is enabled.
738 Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to
739 determine C++11 type inference is supported using the ``auto`` specifier. If
740 this is disabled, ``auto`` will instead be a storage class specifier, as in C
743 C++11 strongly typed enumerations
744 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
746 Use ``__has_feature(cxx_strong_enums)`` or
747 ``__has_extension(cxx_strong_enums)`` to determine if support for strongly
748 typed, scoped enumerations is enabled.
750 C++11 trailing return type
751 ^^^^^^^^^^^^^^^^^^^^^^^^^^
753 Use ``__has_feature(cxx_trailing_return)`` or
754 ``__has_extension(cxx_trailing_return)`` to determine if support for the
755 alternate function declaration syntax with trailing return type is enabled.
757 C++11 Unicode string literals
758 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
760 Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode
761 string literals is enabled.
763 C++11 unrestricted unions
764 ^^^^^^^^^^^^^^^^^^^^^^^^^
766 Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for
767 unrestricted unions is enabled.
769 C++11 user-defined literals
770 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
772 Use ``__has_feature(cxx_user_literals)`` to determine if support for
773 user-defined literals is enabled.
775 C++11 variadic templates
776 ^^^^^^^^^^^^^^^^^^^^^^^^
778 Use ``__has_feature(cxx_variadic_templates)`` or
779 ``__has_extension(cxx_variadic_templates)`` to determine if support for
780 variadic templates is enabled.
785 The features listed below are part of the committee draft for the C++1y
786 standard. As a result, all these features are enabled with the ``-std=c++1y``
787 or ``-std=gnu++1y`` option when compiling C++ code.
789 C++1y binary literals
790 ^^^^^^^^^^^^^^^^^^^^^
792 Use ``__has_feature(cxx_binary_literals)`` or
793 ``__has_extension(cxx_binary_literals)`` to determine whether
794 binary literals (for instance, ``0b10010``) are recognized. Clang supports this
795 feature as an extension in all language modes.
797 C++1y contextual conversions
798 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
800 Use ``__has_feature(cxx_contextual_conversions)`` or
801 ``__has_extension(cxx_contextual_conversions)`` to determine if the C++1y rules
802 are used when performing an implicit conversion for an array bound in a
803 *new-expression*, the operand of a *delete-expression*, an integral constant
804 expression, or a condition in a ``switch`` statement. Clang does not yet
805 support this feature.
810 Use ``__has_feature(cxx_decltype_auto)`` or
811 ``__has_extension(cxx_decltype_auto)`` to determine if support
812 for the ``decltype(auto)`` placeholder type is enabled.
814 C++1y default initializers for aggregates
815 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
817 Use ``__has_feature(cxx_aggregate_nsdmi)`` or
818 ``__has_extension(cxx_aggregate_nsdmi)`` to determine if support
819 for default initializers in aggregate members is enabled.
821 C++1y generalized lambda capture
822 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
824 Use ``__has_feature(cxx_generalized_capture)`` or
825 ``__has_extension(cxx_generalized_capture`` to determine if support for
826 generalized lambda captures is enabled
827 (for instance, ``[n(0)] { return ++n; }``).
828 Clang does not yet support this feature.
830 C++1y generic lambdas
831 ^^^^^^^^^^^^^^^^^^^^^
833 Use ``__has_feature(cxx_generic_lambda)`` or
834 ``__has_extension(cxx_generic_lambda)`` to determine if support for generic
835 (polymorphic) lambdas is enabled
836 (for instance, ``[] (auto x) { return x + 1; }``).
837 Clang does not yet support this feature.
839 C++1y relaxed constexpr
840 ^^^^^^^^^^^^^^^^^^^^^^^
842 Use ``__has_feature(cxx_relaxed_constexpr)`` or
843 ``__has_extension(cxx_relaxed_constexpr)`` to determine if variable
844 declarations, local variable modification, and control flow constructs
845 are permitted in ``constexpr`` functions.
846 Clang's implementation of this feature is incomplete.
848 C++1y return type deduction
849 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
851 Use ``__has_feature(cxx_return_type_deduction)`` or
852 ``__has_extension(cxx_return_type_deduction)`` to determine if support
853 for return type deduction for functions (using ``auto`` as a return type)
855 Clang's implementation of this feature is incomplete.
857 C++1y runtime-sized arrays
858 ^^^^^^^^^^^^^^^^^^^^^^^^^^
860 Use ``__has_feature(cxx_runtime_array)`` or
861 ``__has_extension(cxx_runtime_array)`` to determine if support
862 for arrays of runtime bound (a restricted form of variable-length arrays)
864 Clang's implementation of this feature is incomplete.
866 C++1y variable templates
867 ^^^^^^^^^^^^^^^^^^^^^^^^
869 Use ``__has_feature(cxx_variable_templates)`` or
870 ``__has_extension(cxx_variable_templates)`` to determine if support for
871 templated variable declarations is enabled.
872 Clang does not yet support this feature.
877 The features listed below are part of the C11 standard. As a result, all these
878 features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when
879 compiling C code. Additionally, because these features are all
880 backward-compatible, they are available as extensions in all language modes.
882 C11 alignment specifiers
883 ^^^^^^^^^^^^^^^^^^^^^^^^
885 Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine
886 if support for alignment specifiers using ``_Alignas`` is enabled.
888 C11 atomic operations
889 ^^^^^^^^^^^^^^^^^^^^^
891 Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine
892 if support for atomic types using ``_Atomic`` is enabled. Clang also provides
893 :ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement
894 the ``<stdatomic.h>`` operations on ``_Atomic`` types.
896 C11 generic selections
897 ^^^^^^^^^^^^^^^^^^^^^^
899 Use ``__has_feature(c_generic_selections)`` or
900 ``__has_extension(c_generic_selections)`` to determine if support for generic
901 selections is enabled.
903 As an extension, the C11 generic selection expression is available in all
904 languages supported by Clang. The syntax is the same as that given in the C11
907 In C, type compatibility is decided according to the rules given in the
908 appropriate standard, but in C++, which lacks the type compatibility rules used
909 in C, types are considered compatible only if they are equivalent.
911 C11 ``_Static_assert()``
912 ^^^^^^^^^^^^^^^^^^^^^^^^
914 Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)``
915 to determine if support for compile-time assertions using ``_Static_assert`` is
918 C11 ``_Thread_local``
919 ^^^^^^^^^^^^^^^^^^^^^
921 Use ``__has_feature(c_thread_local)`` to determine if support for
922 ``_Thread_local`` variables is enabled.
924 Checks for Type Traits
925 ======================
927 Clang supports the `GNU C++ type traits
928 <http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the
929 `Microsoft Visual C++ Type traits
930 <http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_. For each
931 supported type trait ``__X``, ``__has_extension(X)`` indicates the presence of
932 the type trait. For example:
936 #if __has_extension(is_convertible_to)
937 template<typename From, typename To>
938 struct is_convertible_to {
939 static const bool value = __is_convertible_to(From, To);
942 // Emulate type trait
945 The following type traits are supported by Clang:
947 * ``__has_nothrow_assign`` (GNU, Microsoft)
948 * ``__has_nothrow_copy`` (GNU, Microsoft)
949 * ``__has_nothrow_constructor`` (GNU, Microsoft)
950 * ``__has_trivial_assign`` (GNU, Microsoft)
951 * ``__has_trivial_copy`` (GNU, Microsoft)
952 * ``__has_trivial_constructor`` (GNU, Microsoft)
953 * ``__has_trivial_destructor`` (GNU, Microsoft)
954 * ``__has_virtual_destructor`` (GNU, Microsoft)
955 * ``__is_abstract`` (GNU, Microsoft)
956 * ``__is_base_of`` (GNU, Microsoft)
957 * ``__is_class`` (GNU, Microsoft)
958 * ``__is_convertible_to`` (Microsoft)
959 * ``__is_empty`` (GNU, Microsoft)
960 * ``__is_enum`` (GNU, Microsoft)
961 * ``__is_interface_class`` (Microsoft)
962 * ``__is_pod`` (GNU, Microsoft)
963 * ``__is_polymorphic`` (GNU, Microsoft)
964 * ``__is_union`` (GNU, Microsoft)
965 * ``__is_literal(type)``: Determines whether the given type is a literal type
966 * ``__is_final``: Determines whether the given type is declared with a
967 ``final`` class-virt-specifier.
968 * ``__underlying_type(type)``: Retrieves the underlying type for a given
969 ``enum`` type. This trait is required to implement the C++11 standard
971 * ``__is_trivially_assignable(totype, fromtype)``: Determines whether a value
972 of type ``totype`` can be assigned to from a value of type ``fromtype`` such
973 that no non-trivial functions are called as part of that assignment. This
974 trait is required to implement the C++11 standard library.
975 * ``__is_trivially_constructible(type, argtypes...)``: Determines whether a
976 value of type ``type`` can be direct-initialized with arguments of types
977 ``argtypes...`` such that no non-trivial functions are called as part of
978 that initialization. This trait is required to implement the C++11 standard
984 The syntax and high level language feature description is in
985 :doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for
986 the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`.
988 Query for this feature with ``__has_extension(blocks)``.
996 According to Cocoa conventions, Objective-C methods with certain names
997 ("``init``", "``alloc``", etc.) always return objects that are an instance of
998 the receiving class's type. Such methods are said to have a "related result
999 type", meaning that a message send to one of these methods will have the same
1000 static type as an instance of the receiver class. For example, given the
1003 .. code-block:: objc
1010 @interface NSArray : NSObject
1013 and this common initialization pattern
1015 .. code-block:: objc
1017 NSArray *array = [[NSArray alloc] init];
1019 the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because
1020 ``alloc`` implicitly has a related result type. Similarly, the type of the
1021 expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a
1022 related result type and its receiver is known to have the type ``NSArray *``.
1023 If neither ``alloc`` nor ``init`` had a related result type, the expressions
1024 would have had type ``id``, as declared in the method signature.
1026 A method with a related result type can be declared by using the type
1027 ``instancetype`` as its result type. ``instancetype`` is a contextual keyword
1028 that is only permitted in the result type of an Objective-C method, e.g.
1030 .. code-block:: objc
1033 + (instancetype)constructAnA;
1036 The related result type can also be inferred for some methods. To determine
1037 whether a method has an inferred related result type, the first word in the
1038 camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered,
1039 and the method will have a related result type if its return type is compatible
1040 with the type of its class and if:
1042 * the first word is "``alloc``" or "``new``", and the method is a class method,
1045 * the first word is "``autorelease``", "``init``", "``retain``", or "``self``",
1046 and the method is an instance method.
1048 If a method with a related result type is overridden by a subclass method, the
1049 subclass method must also return a type that is compatible with the subclass
1052 .. code-block:: objc
1054 @interface NSString : NSObject
1055 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
1058 Related result types only affect the type of a message send or property access
1059 via the given method. In all other respects, a method with a related result
1060 type is treated the same way as method that returns ``id``.
1062 Use ``__has_feature(objc_instancetype)`` to determine whether the
1063 ``instancetype`` contextual keyword is available.
1065 Automatic reference counting
1066 ----------------------------
1068 Clang provides support for :doc:`automated reference counting
1069 <AutomaticReferenceCounting>` in Objective-C, which eliminates the need
1070 for manual ``retain``/``release``/``autorelease`` message sends. There are two
1071 feature macros associated with automatic reference counting:
1072 ``__has_feature(objc_arc)`` indicates the availability of automated reference
1073 counting in general, while ``__has_feature(objc_arc_weak)`` indicates that
1074 automated reference counting also includes support for ``__weak`` pointers to
1075 Objective-C objects.
1077 .. _objc-fixed-enum:
1079 Enumerations with a fixed underlying type
1080 -----------------------------------------
1082 Clang provides support for C++11 enumerations with a fixed underlying type
1083 within Objective-C. For example, one can write an enumeration type as:
1087 typedef enum : unsigned char { Red, Green, Blue } Color;
1089 This specifies that the underlying type, which is used to store the enumeration
1090 value, is ``unsigned char``.
1092 Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed
1093 underlying types is available in Objective-C.
1095 Interoperability with C++11 lambdas
1096 -----------------------------------
1098 Clang provides interoperability between C++11 lambdas and blocks-based APIs, by
1099 permitting a lambda to be implicitly converted to a block pointer with the
1100 corresponding signature. For example, consider an API such as ``NSArray``'s
1101 array-sorting method:
1103 .. code-block:: objc
1105 - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr;
1107 ``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult
1108 (^)(id, id)``, and parameters of this type are generally provided with block
1109 literals as arguments. However, one can also use a C++11 lambda so long as it
1110 provides the same signature (in this case, accepting two parameters of type
1111 ``id`` and returning an ``NSComparisonResult``):
1113 .. code-block:: objc
1115 NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11",
1117 const NSStringCompareOptions comparisonOptions
1118 = NSCaseInsensitiveSearch | NSNumericSearch |
1119 NSWidthInsensitiveSearch | NSForcedOrderingSearch;
1120 NSLocale *currentLocale = [NSLocale currentLocale];
1122 = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult {
1123 NSRange string1Range = NSMakeRange(0, [s1 length]);
1124 return [s1 compare:s2 options:comparisonOptions
1125 range:string1Range locale:currentLocale];
1127 NSLog(@"sorted: %@", sorted);
1129 This code relies on an implicit conversion from the type of the lambda
1130 expression (an unnamed, local class type called the *closure type*) to the
1131 corresponding block pointer type. The conversion itself is expressed by a
1132 conversion operator in that closure type that produces a block pointer with the
1133 same signature as the lambda itself, e.g.,
1135 .. code-block:: objc
1137 operator NSComparisonResult (^)(id, id)() const;
1139 This conversion function returns a new block that simply forwards the two
1140 parameters to the lambda object (which it captures by copy), then returns the
1141 result. The returned block is first copied (with ``Block_copy``) and then
1142 autoreleased. As an optimization, if a lambda expression is immediately
1143 converted to a block pointer (as in the first example, above), then the block
1144 is not copied and autoreleased: rather, it is given the same lifetime as a
1145 block literal written at that point in the program, which avoids the overhead
1146 of copying a block to the heap in the common case.
1148 The conversion from a lambda to a block pointer is only available in
1149 Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory
1150 management (autorelease).
1152 Object Literals and Subscripting
1153 --------------------------------
1155 Clang provides support for :doc:`Object Literals and Subscripting
1156 <ObjectiveCLiterals>` in Objective-C, which simplifies common Objective-C
1157 programming patterns, makes programs more concise, and improves the safety of
1158 container creation. There are several feature macros associated with object
1159 literals and subscripting: ``__has_feature(objc_array_literals)`` tests the
1160 availability of array literals; ``__has_feature(objc_dictionary_literals)``
1161 tests the availability of dictionary literals;
1162 ``__has_feature(objc_subscripting)`` tests the availability of object
1165 Objective-C Autosynthesis of Properties
1166 ---------------------------------------
1168 Clang provides support for autosynthesis of declared properties. Using this
1169 feature, clang provides default synthesis of those properties not declared
1170 @dynamic and not having user provided backing getter and setter methods.
1171 ``__has_feature(objc_default_synthesize_properties)`` checks for availability
1172 of this feature in version of clang being used.
1174 .. _langext-objc_method_family:
1176 The ``objc_method_family`` attribute
1177 ------------------------------------
1179 Many methods in Objective-C have conventional meanings determined by their
1180 selectors. It is sometimes useful to be able to mark a method as having a
1181 particular conventional meaning despite not having the right selector, or as
1182 not having the conventional meaning that its selector would suggest. For these
1183 use cases, we provide an attribute to specifically describe the "method family"
1184 that a method belongs to.
1186 **Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
1187 ``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This
1188 attribute can only be placed at the end of a method declaration:
1190 .. code-block:: objc
1192 - (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
1194 Users who do not wish to change the conventional meaning of a method, and who
1195 merely want to document its non-standard retain and release semantics, should
1196 use the :ref:`retaining behavior attributes <langext-objc-retain-release>`
1199 Query for this feature with ``__has_attribute(objc_method_family)``.
1201 .. _langext-objc-retain-release:
1203 Objective-C retaining behavior attributes
1204 -----------------------------------------
1206 In Objective-C, functions and methods are generally assumed to follow the
1207 `Cocoa Memory Management
1208 <http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_
1209 conventions for ownership of object arguments and
1210 return values. However, there are exceptions, and so Clang provides attributes
1211 to allow these exceptions to be documented. This are used by ARC and the
1212 `static analyzer <http://clang-analyzer.llvm.org>`_ Some exceptions may be
1213 better described using the :ref:`objc_method_family
1214 <langext-objc_method_family>` attribute instead.
1216 **Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``,
1217 ``ns_returns_autoreleased``, ``cf_returns_retained``, and
1218 ``cf_returns_not_retained`` attributes can be placed on methods and functions
1219 that return Objective-C or CoreFoundation objects. They are commonly placed at
1220 the end of a function prototype or method declaration:
1222 .. code-block:: objc
1224 id foo() __attribute__((ns_returns_retained));
1226 - (NSString *)bar:(int)x __attribute__((ns_returns_retained));
1228 The ``*_returns_retained`` attributes specify that the returned object has a +1
1229 retain count. The ``*_returns_not_retained`` attributes specify that the return
1230 object has a +0 retain count, even if the normal convention for its selector
1231 would be +1. ``ns_returns_autoreleased`` specifies that the returned object is
1232 +0, but is guaranteed to live at least as long as the next flush of an
1235 **Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on
1236 an parameter declaration; they specify that the argument is expected to have a
1237 +1 retain count, which will be balanced in some way by the function or method.
1238 The ``ns_consumes_self`` attribute can only be placed on an Objective-C
1239 method; it specifies that the method expects its ``self`` parameter to have a
1240 +1 retain count, which it will balance in some way.
1242 .. code-block:: objc
1244 void foo(__attribute__((ns_consumed)) NSString *string);
1246 - (void) bar __attribute__((ns_consumes_self));
1247 - (void) baz:(id) __attribute__((ns_consumed)) x;
1249 Further examples of these attributes are available in the static analyzer's `list of annotations for analysis
1250 <http://clang-analyzer.llvm.org/annotations.html#cocoa_mem>`_.
1252 Query for these features with ``__has_attribute(ns_consumed)``,
1253 ``__has_attribute(ns_returns_retained)``, etc.
1256 Function Overloading in C
1257 =========================
1259 Clang provides support for C++ function overloading in C. Function overloading
1260 in C is introduced using the ``overloadable`` attribute. For example, one
1261 might provide several overloaded versions of a ``tgsin`` function that invokes
1262 the appropriate standard function computing the sine of a value with ``float``,
1263 ``double``, or ``long double`` precision:
1268 float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
1269 double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
1270 long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
1272 Given these declarations, one can call ``tgsin`` with a ``float`` value to
1273 receive a ``float`` result, with a ``double`` to receive a ``double`` result,
1274 etc. Function overloading in C follows the rules of C++ function overloading
1275 to pick the best overload given the call arguments, with a few C-specific
1278 * Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
1279 floating-point promotion (per C99) rather than as a floating-point conversion
1282 * A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is
1283 considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
1286 * A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
1287 and ``U`` are compatible types. This conversion is given "conversion" rank.
1289 The declaration of ``overloadable`` functions is restricted to function
1290 declarations and definitions. Most importantly, if any function with a given
1291 name is given the ``overloadable`` attribute, then all function declarations
1292 and definitions with that name (and in that scope) must have the
1293 ``overloadable`` attribute. This rule even applies to redeclarations of
1294 functions whose original declaration had the ``overloadable`` attribute, e.g.,
1298 int f(int) __attribute__((overloadable));
1299 float f(float); // error: declaration of "f" must have the "overloadable" attribute
1301 int g(int) __attribute__((overloadable));
1302 int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
1304 Functions marked ``overloadable`` must have prototypes. Therefore, the
1305 following code is ill-formed:
1309 int h() __attribute__((overloadable)); // error: h does not have a prototype
1311 However, ``overloadable`` functions are allowed to use a ellipsis even if there
1312 are no named parameters (as is permitted in C++). This feature is particularly
1313 useful when combined with the ``unavailable`` attribute:
1317 void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
1319 Functions declared with the ``overloadable`` attribute have their names mangled
1320 according to the same rules as C++ function names. For example, the three
1321 ``tgsin`` functions in our motivating example get the mangled names
1322 ``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two
1323 caveats to this use of name mangling:
1325 * Future versions of Clang may change the name mangling of functions overloaded
1326 in C, so you should not depend on an specific mangling. To be completely
1327 safe, we strongly urge the use of ``static inline`` with ``overloadable``
1330 * The ``overloadable`` attribute has almost no meaning when used in C++,
1331 because names will already be mangled and functions are already overloadable.
1332 However, when an ``overloadable`` function occurs within an ``extern "C"``
1333 linkage specification, it's name *will* be mangled in the same way as it
1336 Query for this feature with ``__has_extension(attribute_overloadable)``.
1338 Initializer lists for complex numbers in C
1339 ==========================================
1341 clang supports an extension which allows the following in C:
1346 #include <complex.h>
1347 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf)
1349 This construct is useful because there is no way to separately initialize the
1350 real and imaginary parts of a complex variable in standard C, given that clang
1351 does not support ``_Imaginary``. (Clang also supports the ``__real__`` and
1352 ``__imag__`` extensions from gcc, which help in some cases, but are not usable
1353 in static initializers.)
1355 Note that this extension does not allow eliding the braces; the meaning of the
1356 following two lines is different:
1360 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1)
1361 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0)
1363 This extension also works in C++ mode, as far as that goes, but does not apply
1364 to the C++ ``std::complex``. (In C++11, list initialization allows the same
1365 syntax to be used with ``std::complex`` with the same meaning.)
1370 Clang supports a number of builtin library functions with the same syntax as
1371 GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``,
1372 ``__builtin_choose_expr``, ``__builtin_types_compatible_p``,
1373 ``__sync_fetch_and_add``, etc. In addition to the GCC builtins, Clang supports
1374 a number of builtins that GCC does not, which are listed here.
1376 Please note that Clang does not and will not support all of the GCC builtins
1377 for vector operations. Instead of using builtins, you should use the functions
1378 defined in target-specific header files like ``<xmmintrin.h>``, which define
1379 portable wrappers for these. Many of the Clang versions of these functions are
1380 implemented directly in terms of :ref:`extended vector support
1381 <langext-vectors>` instead of builtins, in order to reduce the number of
1382 builtins that we need to implement.
1384 ``__builtin_readcyclecounter``
1385 ------------------------------
1387 ``__builtin_readcyclecounter`` is used to access the cycle counter register (or
1388 a similar low-latency, high-accuracy clock) on those targets that support it.
1394 __builtin_readcyclecounter()
1400 unsigned long long t0 = __builtin_readcyclecounter();
1402 unsigned long long t1 = __builtin_readcyclecounter();
1403 unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow
1407 The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value,
1408 which may be either global or process/thread-specific depending on the target.
1409 As the backing counters often overflow quickly (on the order of seconds) this
1410 should only be used for timing small intervals. When not supported by the
1411 target, the return value is always zero. This builtin takes no arguments and
1412 produces an unsigned long long result.
1414 Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``.
1416 .. _langext-__builtin_shufflevector:
1418 ``__builtin_shufflevector``
1419 ---------------------------
1421 ``__builtin_shufflevector`` is used to express generic vector
1422 permutation/shuffle/swizzle operations. This builtin is also very important
1423 for the implementation of various target-specific header files like
1430 __builtin_shufflevector(vec1, vec2, index1, index2, ...)
1436 // Identity operation - return 4-element vector V1.
1437 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
1439 // "Splat" element 0 of V1 into a 4-element result.
1440 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
1442 // Reverse 4-element vector V1.
1443 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
1445 // Concatenate every other element of 4-element vectors V1 and V2.
1446 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
1448 // Concatenate every other element of 8-element vectors V1 and V2.
1449 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
1453 The first two arguments to ``__builtin_shufflevector`` are vectors that have
1454 the same element type. The remaining arguments are a list of integers that
1455 specify the elements indices of the first two vectors that should be extracted
1456 and returned in a new vector. These element indices are numbered sequentially
1457 starting with the first vector, continuing into the second vector. Thus, if
1458 ``vec1`` is a 4-element vector, index 5 would refer to the second element of
1461 The result of ``__builtin_shufflevector`` is a vector with the same element
1462 type as ``vec1``/``vec2`` but that has an element count equal to the number of
1465 Query for this feature with ``__has_builtin(__builtin_shufflevector)``.
1467 ``__builtin_unreachable``
1468 -------------------------
1470 ``__builtin_unreachable`` is used to indicate that a specific point in the
1471 program cannot be reached, even if the compiler might otherwise think it can.
1472 This is useful to improve optimization and eliminates certain warnings. For
1473 example, without the ``__builtin_unreachable`` in the example below, the
1474 compiler assumes that the inline asm can fall through and prints a "function
1475 declared '``noreturn``' should not return" warning.
1481 __builtin_unreachable()
1487 void myabort(void) __attribute__((noreturn));
1488 void myabort(void) {
1490 __builtin_unreachable();
1495 The ``__builtin_unreachable()`` builtin has completely undefined behavior.
1496 Since it has undefined behavior, it is a statement that it is never reached and
1497 the optimizer can take advantage of this to produce better code. This builtin
1498 takes no arguments and produces a void result.
1500 Query for this feature with ``__has_builtin(__builtin_unreachable)``.
1505 ``__sync_swap`` is used to atomically swap integers or pointers in memory.
1511 type __sync_swap(type *ptr, type value, ...)
1517 int old_value = __sync_swap(&value, new_value);
1521 The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of
1522 atomic intrinsics to allow code to atomically swap the current value with the
1523 new value. More importantly, it helps developers write more efficient and
1524 correct code by avoiding expensive loops around
1525 ``__sync_bool_compare_and_swap()`` or relying on the platform specific
1526 implementation details of ``__sync_lock_test_and_set()``. The
1527 ``__sync_swap()`` builtin is a full barrier.
1529 Multiprecision Arithmetic Builtins
1530 ----------------------------------
1532 Clang provides a set of builtins which expose multiprecision arithmetic in a
1533 manner amenable to C. They all have the following form:
1537 unsigned x = ..., y = ..., carryin = ..., carryout;
1538 unsigned sum = __builtin_addc(x, y, carryin, &carryout);
1540 Thus one can form a multiprecision addition chain in the following manner:
1544 unsigned *x, *y, *z, carryin=0, carryout;
1545 z[0] = __builtin_addc(x[0], y[0], carryin, &carryout);
1547 z[1] = __builtin_addc(x[1], y[1], carryin, &carryout);
1549 z[2] = __builtin_addc(x[2], y[2], carryin, &carryout);
1551 z[3] = __builtin_addc(x[3], y[3], carryin, &carryout);
1553 The complete list of builtins are:
1557 unsigned short __builtin_addcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout);
1558 unsigned __builtin_addc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout);
1559 unsigned long __builtin_addcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout);
1560 unsigned long long __builtin_addcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout);
1561 unsigned short __builtin_subcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout);
1562 unsigned __builtin_subc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout);
1563 unsigned long __builtin_subcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout);
1564 unsigned long long __builtin_subcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout);
1566 .. _langext-__c11_atomic:
1568 __c11_atomic builtins
1569 ---------------------
1571 Clang provides a set of builtins which are intended to be used to implement
1572 C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the
1573 ``_explicit`` form of the corresponding C11 operation, and are named with a
1574 ``__c11_`` prefix. The supported operations are:
1576 * ``__c11_atomic_init``
1577 * ``__c11_atomic_thread_fence``
1578 * ``__c11_atomic_signal_fence``
1579 * ``__c11_atomic_is_lock_free``
1580 * ``__c11_atomic_store``
1581 * ``__c11_atomic_load``
1582 * ``__c11_atomic_exchange``
1583 * ``__c11_atomic_compare_exchange_strong``
1584 * ``__c11_atomic_compare_exchange_weak``
1585 * ``__c11_atomic_fetch_add``
1586 * ``__c11_atomic_fetch_sub``
1587 * ``__c11_atomic_fetch_and``
1588 * ``__c11_atomic_fetch_or``
1589 * ``__c11_atomic_fetch_xor``
1591 Non-standard C++11 Attributes
1592 =============================
1594 Clang's non-standard C++11 attributes live in the ``clang`` attribute
1597 The ``clang::fallthrough`` attribute
1598 ------------------------------------
1600 The ``clang::fallthrough`` attribute is used along with the
1601 ``-Wimplicit-fallthrough`` argument to annotate intentional fall-through
1602 between switch labels. It can only be applied to a null statement placed at a
1603 point of execution between any statement and the next switch label. It is
1604 common to mark these places with a specific comment, but this attribute is
1605 meant to replace comments with a more strict annotation, which can be checked
1606 by the compiler. This attribute doesn't change semantics of the code and can
1607 be used wherever an intended fall-through occurs. It is designed to mimic
1608 control-flow statements like ``break;``, so it can be placed in most places
1609 where ``break;`` can, but only if there are no statements on the execution path
1610 between it and the next switch label.
1616 // compile with -Wimplicit-fallthrough
1619 case 33: // no warning: no statements between case labels
1621 case 44: // warning: unannotated fall-through
1623 [[clang::fallthrough]];
1624 case 55: // no warning
1631 [[clang::fallthrough]];
1633 case 66: // no warning
1635 [[clang::fallthrough]]; // warning: fallthrough annotation does not
1636 // directly precede case label
1638 case 77: // warning: unannotated fall-through
1642 ``gnu::`` attributes
1643 --------------------
1645 Clang also supports GCC's ``gnu`` attribute namespace. All GCC attributes which
1646 are accepted with the ``__attribute__((foo))`` syntax are also accepted as
1647 ``[[gnu::foo]]``. This only extends to attributes which are specified by GCC
1648 (see the list of `GCC function attributes
1649 <http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_, `GCC variable
1650 attributes <http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html>`_, and
1651 `GCC type attributes
1652 <http://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html>`_. As with the GCC
1653 implementation, these attributes must appertain to the *declarator-id* in a
1654 declaration, which means they must go either at the start of the declaration or
1655 immediately after the name being declared.
1657 For example, this applies the GNU ``unused`` attribute to ``a`` and ``f``, and
1658 also applies the GNU ``noreturn`` attribute to ``f``.
1662 [[gnu::unused]] int a, f [[gnu::noreturn]] ();
1664 Target-Specific Extensions
1665 ==========================
1667 Clang supports some language features conditionally on some targets.
1669 X86/X86-64 Language Extensions
1670 ------------------------------
1672 The X86 backend has these language extensions:
1674 Memory references off the GS segment
1675 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1677 Annotating a pointer with address space #256 causes it to be code generated
1678 relative to the X86 GS segment register, and address space #257 causes it to be
1679 relative to the X86 FS segment. Note that this is a very very low-level
1680 feature that should only be used if you know what you're doing (for example in
1687 #define GS_RELATIVE __attribute__((address_space(256)))
1688 int foo(int GS_RELATIVE *P) {
1692 Which compiles to (on X86-32):
1698 movl %gs:(%eax), %eax
1701 Extensions for Static Analysis
1702 ==============================
1704 Clang supports additional attributes that are useful for documenting program
1705 invariants and rules for static analysis tools, such as the `Clang Static
1706 Analyzer <http://clang-analyzer.llvm.org/>`_. These attributes are documented
1707 in the analyzer's `list of source-level annotations
1708 <http://clang-analyzer.llvm.org/annotations.html>`_.
1711 Extensions for Dynamic Analysis
1712 ===============================
1714 .. _langext-address_sanitizer:
1719 Use ``__has_feature(address_sanitizer)`` to check if the code is being built
1720 with :doc:`AddressSanitizer`.
1722 Use ``__attribute__((no_sanitize_address))``
1723 on a function declaration
1724 to specify that address safety instrumentation (e.g. AddressSanitizer) should
1725 not be applied to that function.
1727 .. _langext-thread_sanitizer:
1732 Use ``__has_feature(thread_sanitizer)`` to check if the code is being built
1733 with :doc:`ThreadSanitizer`.
1735 Use ``__attribute__((no_sanitize_thread))`` on a function declaration
1736 to specify that checks for data races on plain (non-atomic) memory accesses
1737 should not be inserted by ThreadSanitizer.
1738 The function may still be instrumented by the tool
1739 to avoid false positives in other places.
1741 .. _langext-memory_sanitizer:
1745 Use ``__has_feature(memory_sanitizer)`` to check if the code is being built
1746 with :doc:`MemorySanitizer`.
1748 Use ``__attribute__((no_sanitize_memory))`` on a function declaration
1749 to specify that checks for uninitialized memory should not be inserted
1750 (e.g. by MemorySanitizer). The function may still be instrumented by the tool
1751 to avoid false positives in other places.
1754 Thread-Safety Annotation Checking
1755 =================================
1757 Clang supports additional attributes for checking basic locking policies in
1758 multithreaded programs. Clang currently parses the following list of
1759 attributes, although **the implementation for these annotations is currently in
1760 development.** For more details, see the `GCC implementation
1761 <http://gcc.gnu.org/wiki/ThreadSafetyAnnotation>`_.
1763 ``no_thread_safety_analysis``
1764 -----------------------------
1766 Use ``__attribute__((no_thread_safety_analysis))`` on a function declaration to
1767 specify that the thread safety analysis should not be run on that function.
1768 This attribute provides an escape hatch (e.g. for situations when it is
1769 difficult to annotate the locking policy).
1774 Use ``__attribute__((lockable))`` on a class definition to specify that it has
1775 a lockable type (e.g. a Mutex class). This annotation is primarily used to
1781 Use ``__attribute__((scoped_lockable))`` on a class definition to specify that
1782 it has a "scoped" lockable type. Objects of this type will acquire the lock
1783 upon construction and release it upon going out of scope. This annotation is
1784 primarily used to check consistency.
1789 Use ``__attribute__((guarded_var))`` on a variable declaration to specify that
1790 the variable must be accessed while holding some lock.
1795 Use ``__attribute__((pt_guarded_var))`` on a pointer declaration to specify
1796 that the pointer must be dereferenced while holding some lock.
1801 Use ``__attribute__((guarded_by(l)))`` on a variable declaration to specify
1802 that the variable must be accessed while holding lock ``l``.
1804 ``pt_guarded_by(l)``
1805 --------------------
1807 Use ``__attribute__((pt_guarded_by(l)))`` on a pointer declaration to specify
1808 that the pointer must be dereferenced while holding lock ``l``.
1810 ``acquired_before(...)``
1811 ------------------------
1813 Use ``__attribute__((acquired_before(...)))`` on a declaration of a lockable
1814 variable to specify that the lock must be acquired before all attribute
1815 arguments. Arguments must be lockable type, and there must be at least one
1818 ``acquired_after(...)``
1819 -----------------------
1821 Use ``__attribute__((acquired_after(...)))`` on a declaration of a lockable
1822 variable to specify that the lock must be acquired after all attribute
1823 arguments. Arguments must be lockable type, and there must be at least one
1826 ``exclusive_lock_function(...)``
1827 --------------------------------
1829 Use ``__attribute__((exclusive_lock_function(...)))`` on a function declaration
1830 to specify that the function acquires all listed locks exclusively. This
1831 attribute takes zero or more arguments: either of lockable type or integers
1832 indexing into function parameters of lockable type. If no arguments are given,
1833 the acquired lock is implicitly ``this`` of the enclosing object.
1835 ``shared_lock_function(...)``
1836 -----------------------------
1838 Use ``__attribute__((shared_lock_function(...)))`` on a function declaration to
1839 specify that the function acquires all listed locks, although the locks may be
1840 shared (e.g. read locks). This attribute takes zero or more arguments: either
1841 of lockable type or integers indexing into function parameters of lockable
1842 type. If no arguments are given, the acquired lock is implicitly ``this`` of
1843 the enclosing object.
1845 ``exclusive_trylock_function(...)``
1846 -----------------------------------
1848 Use ``__attribute__((exclusive_lock_function(...)))`` on a function declaration
1849 to specify that the function will try (without blocking) to acquire all listed
1850 locks exclusively. This attribute takes one or more arguments. The first
1851 argument is an integer or boolean value specifying the return value of a
1852 successful lock acquisition. The remaining arugments are either of lockable
1853 type or integers indexing into function parameters of lockable type. If only
1854 one argument is given, the acquired lock is implicitly ``this`` of the
1857 ``shared_trylock_function(...)``
1858 --------------------------------
1860 Use ``__attribute__((shared_lock_function(...)))`` on a function declaration to
1861 specify that the function will try (without blocking) to acquire all listed
1862 locks, although the locks may be shared (e.g. read locks). This attribute
1863 takes one or more arguments. The first argument is an integer or boolean value
1864 specifying the return value of a successful lock acquisition. The remaining
1865 arugments are either of lockable type or integers indexing into function
1866 parameters of lockable type. If only one argument is given, the acquired lock
1867 is implicitly ``this`` of the enclosing object.
1869 ``unlock_function(...)``
1870 ------------------------
1872 Use ``__attribute__((unlock_function(...)))`` on a function declaration to
1873 specify that the function release all listed locks. This attribute takes zero
1874 or more arguments: either of lockable type or integers indexing into function
1875 parameters of lockable type. If no arguments are given, the acquired lock is
1876 implicitly ``this`` of the enclosing object.
1878 ``lock_returned(l)``
1879 --------------------
1881 Use ``__attribute__((lock_returned(l)))`` on a function declaration to specify
1882 that the function returns lock ``l`` (``l`` must be of lockable type). This
1883 annotation is used to aid in resolving lock expressions.
1885 ``locks_excluded(...)``
1886 -----------------------
1888 Use ``__attribute__((locks_excluded(...)))`` on a function declaration to
1889 specify that the function must not be called with the listed locks. Arguments
1890 must be lockable type, and there must be at least one argument.
1892 ``exclusive_locks_required(...)``
1893 ---------------------------------
1895 Use ``__attribute__((exclusive_locks_required(...)))`` on a function
1896 declaration to specify that the function must be called while holding the
1897 listed exclusive locks. Arguments must be lockable type, and there must be at
1900 ``shared_locks_required(...)``
1901 ------------------------------
1903 Use ``__attribute__((shared_locks_required(...)))`` on a function declaration
1904 to specify that the function must be called while holding the listed shared
1905 locks. Arguments must be lockable type, and there must be at least one
1908 Type Safety Checking
1909 ====================
1911 Clang supports additional attributes to enable checking type safety properties
1912 that can't be enforced by C type system. Usecases include:
1914 * MPI library implementations, where these attributes enable checking that
1915 buffer type matches the passed ``MPI_Datatype``;
1916 * for HDF5 library there is a similar usecase as MPI;
1917 * checking types of variadic functions' arguments for functions like
1918 ``fcntl()`` and ``ioctl()``.
1920 You can detect support for these attributes with ``__has_attribute()``. For
1925 #if defined(__has_attribute)
1926 # if __has_attribute(argument_with_type_tag) && \
1927 __has_attribute(pointer_with_type_tag) && \
1928 __has_attribute(type_tag_for_datatype)
1929 # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
1930 /* ... other macros ... */
1934 #if !defined(ATTR_MPI_PWT)
1935 # define ATTR_MPI_PWT(buffer_idx, type_idx)
1938 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
1941 ``argument_with_type_tag(...)``
1942 -------------------------------
1944 Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
1945 type_tag_idx)))`` on a function declaration to specify that the function
1946 accepts a type tag that determines the type of some other argument.
1947 ``arg_kind`` is an identifier that should be used when annotating all
1948 applicable type tags.
1950 This attribute is primarily useful for checking arguments of variadic functions
1951 (``pointer_with_type_tag`` can be used in most of non-variadic cases).
1957 int fcntl(int fd, int cmd, ...)
1958 __attribute__(( argument_with_type_tag(fcntl,3,2) ));
1960 ``pointer_with_type_tag(...)``
1961 ------------------------------
1963 Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))``
1964 on a function declaration to specify that the function accepts a type tag that
1965 determines the pointee type of some other pointer argument.
1971 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
1972 __attribute__(( pointer_with_type_tag(mpi,1,3) ));
1974 ``type_tag_for_datatype(...)``
1975 ------------------------------
1977 Clang supports annotating type tags of two forms.
1979 * **Type tag that is an expression containing a reference to some declared
1980 identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a
1981 declaration with that identifier:
1985 extern struct mpi_datatype mpi_datatype_int
1986 __attribute__(( type_tag_for_datatype(mpi,int) ));
1987 #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
1989 * **Type tag that is an integral literal.** Introduce a ``static const``
1990 variable with a corresponding initializer value and attach
1991 ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration,
1996 #define MPI_INT ((MPI_Datatype) 42)
1997 static const MPI_Datatype mpi_datatype_int
1998 __attribute__(( type_tag_for_datatype(mpi,int) )) = 42
2000 The attribute also accepts an optional third argument that determines how the
2001 expression is compared to the type tag. There are two supported flags:
2003 * ``layout_compatible`` will cause types to be compared according to
2004 layout-compatibility rules (C++11 [class.mem] p 17, 18). This is
2005 implemented to support annotating types like ``MPI_DOUBLE_INT``.
2012 struct internal_mpi_double_int { double d; int i; };
2013 extern struct mpi_datatype mpi_datatype_double_int
2014 __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) ));
2016 #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
2019 struct my_pair { double a; int b; };
2020 struct my_pair *buffer;
2021 MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning
2023 struct my_int_pair { int a; int b; }
2024 struct my_int_pair *buffer2;
2025 MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element
2026 // type 'struct my_int_pair'
2027 // doesn't match specified MPI_Datatype
2029 * ``must_be_null`` specifies that the expression should be a null pointer
2030 constant, for example:
2035 extern struct mpi_datatype mpi_datatype_null
2036 __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
2038 #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
2041 MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL
2042 // was specified but buffer
2043 // is not a null pointer
2045 Format String Checking
2046 ======================
2048 Clang supports the ``format`` attribute, which indicates that the function
2049 accepts a ``printf`` or ``scanf``-like format string and corresponding
2050 arguments or a ``va_list`` that contains these arguments.
2052 Please see `GCC documentation about format attribute
2053 <http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
2054 about attribute syntax.
2056 Clang implements two kinds of checks with this attribute.
2058 #. Clang checks that the function with the ``format`` attribute is called with
2059 a format string that uses format specifiers that are allowed, and that
2060 arguments match the format string. This is the ``-Wformat`` warning, it is
2063 #. Clang checks that the format string argument is a literal string. This is
2064 the ``-Wformat-nonliteral`` warning, it is off by default.
2066 Clang implements this mostly the same way as GCC, but there is a difference
2067 for functions that accept a ``va_list`` argument (for example, ``vprintf``).
2068 GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
2069 fuctions. Clang does not warn if the format string comes from a function
2070 parameter, where the function is annotated with a compatible attribute,
2071 otherwise it warns. For example:
2075 __attribute__((__format__ (__scanf__, 1, 3)))
2076 void foo(const char* s, char *buf, ...) {
2080 vprintf(s, ap); // warning: format string is not a string literal
2083 In this case we warn because ``s`` contains a format string for a
2084 ``scanf``-like function, but it is passed to a ``printf``-like function.
2086 If the attribute is removed, clang still warns, because the format string is
2087 not a string literal.
2093 __attribute__((__format__ (__printf__, 1, 3)))
2094 void foo(const char* s, char *buf, ...) {
2098 vprintf(s, ap); // warning
2101 In this case Clang does not warn because the format string ``s`` and
2102 the corresponding arguments are annotated. If the arguments are
2103 incorrect, the caller of ``foo`` will receive a warning.