| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| "http://www.w3.org/TR/html4/strict.dtd"> |
| <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ --> |
| <html> |
| <head> |
| <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Clang Language Extensions</title> |
| <link type="text/css" rel="stylesheet" href="../menu.css"> |
| <link type="text/css" rel="stylesheet" href="../content.css"> |
| <style type="text/css"> |
| td { |
| vertical-align: top; |
| } |
| th { background-color: #ffddaa; } |
| </style> |
| </head> |
| <body> |
| |
| <!--#include virtual="../menu.html.incl"--> |
| |
| <div id="content"> |
| |
| <h1>Clang Language Extensions</h1> |
| |
| <ul> |
| <li><a href="#intro">Introduction</a></li> |
| <li><a href="#feature_check">Feature Checking Macros</a></li> |
| <li><a href="#has_include">Include File Checking Macros</a></li> |
| <li><a href="#builtinmacros">Builtin Macros</a></li> |
| <li><a href="#vectors">Vectors and Extended Vectors</a></li> |
| <li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li> |
| <li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li> |
| <li><a href="#user_specified_system_framework">'User-Specified' System Frameworks</a></li> |
| <li><a href="#availability">Availability attribute</a></li> |
| <li><a href="#checking_language_features">Checks for Standard Language Features</a> |
| <ul> |
| <li><a href="#cxx98">C++98</a> |
| <ul> |
| <li><a href="#cxx_exceptions">C++ exceptions</a></li> |
| <li><a href="#cxx_rtti">C++ RTTI</a></li> |
| </ul></li> |
| <li><a href="#cxx11">C++11</a> |
| <ul> |
| <li><a href="#cxx_access_control_sfinae">C++11 SFINAE includes access control</a></li> |
| <li><a href="#cxx_alias_templates">C++11 alias templates</a></li> |
| <li><a href="#cxx_alignas">C++11 alignment specifiers</a></li> |
| <li><a href="#cxx_attributes">C++11 attributes</a></li> |
| <li><a href="#cxx_constexpr">C++11 generalized constant expressions</a></li> |
| <li><a href="#cxx_decltype">C++11 <tt>decltype()</tt></a></li> |
| <li><a href="#cxx_default_function_template_args">C++11 default template arguments in function templates</a></li> |
| <li><a href="#cxx_defaulted_functions">C++11 defaulted functions</a></li> |
| <li><a href="#cxx_delegating_constructor">C++11 delegating constructors</a></li> |
| <li><a href="#cxx_deleted_functions">C++11 deleted functions</a></li> |
| <li><a href="#cxx_explicit_conversions">C++11 explicit conversion functions</a></li> |
| <li><a href="#cxx_generalized_initializers">C++11 generalized initializers</a></li> |
| <li><a href="#cxx_implicit_moves">C++11 implicit move constructors/assignment operators</a></li> |
| <li><a href="#cxx_inheriting_constructors">C++11 inheriting constructors</a></li> |
| <li><a href="#cxx_inline_namespaces">C++11 inline namespaces</a></li> |
| <li><a href="#cxx_lambdas">C++11 lambdas</a></li> |
| <li><a href="#cxx_local_type_template_args">C++11 local and unnamed types as template arguments</a></li> |
| <li><a href="#cxx_noexcept">C++11 noexcept specification</a></li> |
| <li><a href="#cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</a></li> |
| <li><a href="#cxx_nullptr">C++11 nullptr</a></li> |
| <li><a href="#cxx_override_control">C++11 override control</a></li> |
| <li><a href="#cxx_range_for">C++11 range-based for loop</a></li> |
| <li><a href="#cxx_raw_string_literals">C++11 raw string literals</a></li> |
| <li><a href="#cxx_rvalue_references">C++11 rvalue references</a></li> |
| <li><a href="#cxx_reference_qualified_functions">C++11 reference-qualified functions</a></li> |
| <li><a href="#cxx_static_assert">C++11 <tt>static_assert()</tt></a></li> |
| <li><a href="#cxx_auto_type">C++11 type inference</a></li> |
| <li><a href="#cxx_strong_enums">C++11 strongly-typed enumerations</a></li> |
| <li><a href="#cxx_trailing_return">C++11 trailing return type</a></li> |
| <li><a href="#cxx_unicode_literals">C++11 Unicode string literals</a></li> |
| <li><a href="#cxx_unrestricted_unions">C++11 unrestricted unions</a></li> |
| <li><a href="#cxx_user_literals">C++11 user-defined literals</a></li> |
| <li><a href="#cxx_variadic_templates">C++11 variadic templates</a></li> |
| </ul></li> |
| <li><a href="#c11">C11</a> |
| <ul> |
| <li><a href="#c_alignas">C11 alignment specifiers</a></li> |
| <li><a href="#c_atomic">C11 atomic operations</a></li> |
| <li><a href="#c_generic_selections">C11 generic selections</a></li> |
| <li><a href="#c_static_assert">C11 <tt>_Static_assert()</tt></a></li> |
| </ul></li> |
| </ul></li> |
| <li><a href="#checking_type_traits">Checks for Type Traits</a></li> |
| <li><a href="#blocks">Blocks</a></li> |
| <li><a href="#objc_features">Objective-C Features</a> |
| <ul> |
| <li><a href="#objc_instancetype">Related result types</a></li> |
| <li><a href="#objc_arc">Automatic reference counting</a></li> |
| <li><a href="#objc_fixed_enum">Enumerations with a fixed underlying type</a></li> |
| <li><a href="#objc_lambdas">Interoperability with C++11 lambdas</a></li> |
| <li><a href="#objc_object_literals_subscripting">Object Literals and Subscripting</a></li> |
| </ul> |
| </li> |
| <li><a href="#overloading-in-c">Function Overloading in C</a></li> |
| <li><a href="#complex-list-init">Initializer lists for complex numbers in C</a></li> |
| <li><a href="#builtins">Builtin Functions</a> |
| <ul> |
| <li><a href="#__builtin_readcyclecounter">__builtin_readcyclecounter</a></li> |
| <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li> |
| <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li> |
| <li><a href="#__sync_swap">__sync_swap</a></li> |
| </ul> |
| </li> |
| <li><a href="#non-standard-attributes">Non-standard C++11 Attributes</a> |
| <ul> |
| <li><a href="#clang__fallthrough">The <tt>clang::fallthrough</tt> attribute</a></li> |
| </ul> |
| </li> |
| <li><a href="#targetspecific">Target-Specific Extensions</a> |
| <ul> |
| <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li> |
| </ul> |
| </li> |
| <li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li> |
| <li><a href="#dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</a> |
| <ul> |
| <li><a href="#address_sanitizer">AddressSanitizer</a></li> |
| </ul> |
| </li> |
| <li><a href="#threadsafety">Thread Safety Annotation Checking</a> |
| <ul> |
| <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li> |
| <li><a href="#ts_lockable"><tt>lockable</tt></a></li> |
| <li><a href="#ts_scopedlockable"><tt>scoped_lockable</tt></a></li> |
| <li><a href="#ts_guardedvar"><tt>guarded_var</tt></a></li> |
| <li><a href="#ts_ptguardedvar"><tt>pt_guarded_var</tt></a></li> |
| <li><a href="#ts_guardedby"><tt>guarded_by(l)</tt></a></li> |
| <li><a href="#ts_ptguardedby"><tt>pt_guarded_by(l)</tt></a></li> |
| <li><a href="#ts_acquiredbefore"><tt>acquired_before(...)</tt></a></li> |
| <li><a href="#ts_acquiredafter"><tt>acquired_after(...)</tt></a></li> |
| <li><a href="#ts_elf"><tt>exclusive_lock_function(...)</tt></a></li> |
| <li><a href="#ts_slf"><tt>shared_lock_function(...)</tt></a></li> |
| <li><a href="#ts_etf"><tt>exclusive_trylock_function(...)</tt></a></li> |
| <li><a href="#ts_stf"><tt>shared_trylock_function(...)</tt></a></li> |
| <li><a href="#ts_uf"><tt>unlock_function(...)</tt></a></li> |
| <li><a href="#ts_lr"><tt>lock_returned(l)</tt></a></li> |
| <li><a href="#ts_le"><tt>locks_excluded(...)</tt></a></li> |
| <li><a href="#ts_elr"><tt>exclusive_locks_required(...)</tt></a></li> |
| <li><a href="#ts_slr"><tt>shared_locks_required(...)</tt></a></li> |
| </ul> |
| </li> |
| <li><a href="#type_safety">Type Safety Checking</a> |
| <ul> |
| <li><a href="#argument_with_type_tag"><tt>argument_with_type_tag(...)</tt></a></li> |
| <li><a href="#pointer_with_type_tag"><tt>pointer_with_type_tag(...)</tt></a></li> |
| <li><a href="#type_tag_for_datatype"><tt>type_tag_for_datatype(...)</tt></a></li> |
| </ul> |
| </li> |
| </ul> |
| |
| <!-- ======================================================================= --> |
| <h2 id="intro">Introduction</h2> |
| <!-- ======================================================================= --> |
| |
| <p>This document describes the language extensions provided by Clang. In |
| addition to the language extensions listed here, Clang aims to support a broad |
| range of GCC extensions. Please see the <a |
| href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for |
| more information on these extensions.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="feature_check">Feature Checking Macros</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Language extensions can be very useful, but only if you know you can depend |
| on them. In order to allow fine-grain features checks, we support three builtin |
| function-like macros. This allows you to directly test for a feature in your |
| code without having to resort to something like autoconf or fragile "compiler |
| version checks".</p> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__has_builtin">__has_builtin</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p>This function-like macro takes a single identifier argument that is the name |
| of a builtin function. It evaluates to 1 if the builtin is supported or 0 if |
| not. It can be used like this:</p> |
| |
| <blockquote> |
| <pre> |
| #ifndef __has_builtin // Optional of course. |
| #define __has_builtin(x) 0 // Compatibility with non-clang compilers. |
| #endif |
| |
| ... |
| #if __has_builtin(__builtin_trap) |
| __builtin_trap(); |
| #else |
| abort(); |
| #endif |
| ... |
| </pre> |
| </blockquote> |
| |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__has_feature_extension"> __has_feature and __has_extension</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p>These function-like macros take a single identifier argument that is the |
| name of a feature. <code>__has_feature</code> evaluates to 1 if the feature |
| is both supported by Clang and standardized in the current language standard |
| or 0 if not (but see <a href="#has_feature_back_compat">below</a>), while |
| <code>__has_extension</code> evaluates to 1 if the feature is supported by |
| Clang in the current language (either as a language extension or a standard |
| language feature) or 0 if not. They can be used like this:</p> |
| |
| <blockquote> |
| <pre> |
| #ifndef __has_feature // Optional of course. |
| #define __has_feature(x) 0 // Compatibility with non-clang compilers. |
| #endif |
| #ifndef __has_extension |
| #define __has_extension __has_feature // Compatibility with pre-3.0 compilers. |
| #endif |
| |
| ... |
| #if __has_feature(cxx_rvalue_references) |
| // This code will only be compiled with the -std=c++11 and -std=gnu++11 |
| // options, because rvalue references are only standardized in C++11. |
| #endif |
| |
| #if __has_extension(cxx_rvalue_references) |
| // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98 |
| // and -std=gnu++98 options, because rvalue references are supported as a |
| // language extension in C++98. |
| #endif |
| </pre> |
| </blockquote> |
| |
| <p id="has_feature_back_compat">For backwards compatibility reasons, |
| <code>__has_feature</code> can also be used to test for support for |
| non-standardized features, i.e. features not prefixed <code>c_</code>, |
| <code>cxx_</code> or <code>objc_</code>.</p> |
| |
| <p id="has_feature_for_non_language_features"> |
| Another use of <code>__has_feature</code> is to check for compiler features |
| not related to the language standard, such as e.g. |
| <a href="AddressSanitizer.html">AddressSanitizer</a>. |
| |
| <p>If the <code>-pedantic-errors</code> option is given, |
| <code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p> |
| |
| <p>The feature tag is described along with the language feature below.</p> |
| |
| <p>The feature name or extension name can also be specified with a preceding and |
| following <code>__</code> (double underscore) to avoid interference from a macro |
| with the same name. For instance, <code>__cxx_rvalue_references__</code> can be |
| used instead of <code>cxx_rvalue_references</code>.</p> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__has_attribute">__has_attribute</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p>This function-like macro takes a single identifier argument that is the name |
| of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It |
| can be used like this:</p> |
| |
| <blockquote> |
| <pre> |
| #ifndef __has_attribute // Optional of course. |
| #define __has_attribute(x) 0 // Compatibility with non-clang compilers. |
| #endif |
| |
| ... |
| #if __has_attribute(always_inline) |
| #define ALWAYS_INLINE __attribute__((always_inline)) |
| #else |
| #define ALWAYS_INLINE |
| #endif |
| ... |
| </pre> |
| </blockquote> |
| |
| <p>The attribute name can also be specified with a preceding and |
| following <code>__</code> (double underscore) to avoid interference from a macro |
| with the same name. For instance, <code>__always_inline__</code> can be used |
| instead of <code>always_inline</code>.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="has_include">Include File Checking Macros</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Not all developments systems have the same include files. |
| The <a href="#__has_include">__has_include</a> and |
| <a href="#__has_include_next">__has_include_next</a> macros allow you to |
| check for the existence of an include file before doing |
| a possibly failing #include directive.</p> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__has_include">__has_include</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p>This function-like macro takes a single file name string argument that |
| is the name of an include file. It evaluates to 1 if the file can |
| be found using the include paths, or 0 otherwise:</p> |
| |
| <blockquote> |
| <pre> |
| // Note the two possible file name string formats. |
| #if __has_include("myinclude.h") && __has_include(<stdint.h>) |
| # include "myinclude.h" |
| #endif |
| |
| // To avoid problem with non-clang compilers not having this macro. |
| #if defined(__has_include) && __has_include("myinclude.h") |
| # include "myinclude.h" |
| #endif |
| </pre> |
| </blockquote> |
| |
| <p>To test for this feature, use #if defined(__has_include).</p> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__has_include_next">__has_include_next</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p>This function-like macro takes a single file name string argument that |
| is the name of an include file. It is like __has_include except that it |
| looks for the second instance of the given file found in the include |
| paths. It evaluates to 1 if the second instance of the file can |
| be found using the include paths, or 0 otherwise:</p> |
| |
| <blockquote> |
| <pre> |
| // Note the two possible file name string formats. |
| #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>) |
| # include_next "myinclude.h" |
| #endif |
| |
| // To avoid problem with non-clang compilers not having this macro. |
| #if defined(__has_include_next) && __has_include_next("myinclude.h") |
| # include_next "myinclude.h" |
| #endif |
| </pre> |
| </blockquote> |
| |
| <p>Note that __has_include_next, like the GNU extension |
| #include_next directive, is intended for use in headers only, |
| and will issue a warning if used in the top-level compilation |
| file. A warning will also be issued if an absolute path |
| is used in the file argument.</p> |
| |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__has_warning">__has_warning</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p>This function-like macro takes a string literal that represents a command |
| line option for a warning and returns true if that is a valid warning |
| option.</p> |
| |
| <blockquote> |
| <pre> |
| #if __has_warning("-Wformat") |
| ... |
| #endif |
| </pre> |
| </blockquote> |
| |
| <!-- ======================================================================= --> |
| <h2 id="builtinmacros">Builtin Macros</h2> |
| <!-- ======================================================================= --> |
| |
| <dl> |
| <dt><code>__BASE_FILE__</code></dt> |
| <dd>Defined to a string that contains the name of the main input |
| file passed to Clang.</dd> |
| |
| <dt><code>__COUNTER__</code></dt> |
| <dd>Defined to an integer value that starts at zero and is |
| incremented each time the <code>__COUNTER__</code> macro is |
| expanded.</dd> |
| |
| <dt><code>__INCLUDE_LEVEL__</code></dt> |
| <dd>Defined to an integral value that is the include depth of the |
| file currently being translated. For the main file, this value is |
| zero.</dd> |
| |
| <dt><code>__TIMESTAMP__</code></dt> |
| <dd>Defined to the date and time of the last modification of the |
| current source file.</dd> |
| |
| <dt><code>__clang__</code></dt> |
| <dd>Defined when compiling with Clang</dd> |
| |
| <dt><code>__clang_major__</code></dt> |
| <dd>Defined to the major marketing version number of Clang (e.g., the |
| 2 in 2.0.1). Note that marketing version numbers should not be used to |
| check for language features, as different vendors use different numbering |
| schemes. Instead, use the <a href="#feature_check">feature checking |
| macros</a>.</dd> |
| |
| <dt><code>__clang_minor__</code></dt> |
| <dd>Defined to the minor version number of Clang (e.g., the 0 in |
| 2.0.1). Note that marketing version numbers should not be used to |
| check for language features, as different vendors use different numbering |
| schemes. Instead, use the <a href="#feature_check">feature checking |
| macros</a>.</dd> |
| |
| <dt><code>__clang_patchlevel__</code></dt> |
| <dd>Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).</dd> |
| |
| <dt><code>__clang_version__</code></dt> |
| <dd>Defined to a string that captures the Clang marketing version, including |
| the Subversion tag or revision number, e.g., "1.5 (trunk 102332)".</dd> |
| </dl> |
| |
| <!-- ======================================================================= --> |
| <h2 id="vectors">Vectors and Extended Vectors</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Supports the GCC, OpenCL, AltiVec and NEON vector extensions.</p> |
| |
| <p>OpenCL vector types are created using <tt>ext_vector_type</tt> attribute. It |
| support for <tt>V.xyzw</tt> syntax and other tidbits as seen in OpenCL. An |
| example is:</p> |
| |
| <blockquote> |
| <pre> |
| typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>; |
| typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>; |
| |
| float4 foo(float2 a, float2 b) { |
| float4 c; |
| c.xz = a; |
| c.yw = b; |
| return c; |
| } |
| </pre> |
| </blockquote> |
| |
| <p>Query for this feature with |
| <tt>__has_extension(attribute_ext_vector_type)</tt>.</p> |
| |
| <p>Giving <tt>-faltivec</tt> option to clang enables support for AltiVec vector |
| syntax and functions. For example:</p> |
| |
| <blockquote> |
| <pre> |
| vector float foo(vector int a) { |
| vector int b; |
| b = vec_add(a, a) + a; |
| return (vector float)b; |
| } |
| </pre> |
| </blockquote> |
| |
| <p>NEON vector types are created using <tt>neon_vector_type</tt> and |
| <tt>neon_polyvector_type</tt> attributes. For example:</p> |
| |
| <blockquote> |
| <pre> |
| typedef <b>__attribute__((neon_vector_type(8)))</b> int8_t int8x8_t; |
| typedef <b>__attribute__((neon_polyvector_type(16)))</b> poly8_t poly8x16_t; |
| |
| int8x8_t foo(int8x8_t a) { |
| int8x8_t v; |
| v = a; |
| return v; |
| } |
| </pre> |
| </blockquote> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="vector_literals">Vector Literals</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p>Vector literals can be used to create vectors from a set of scalars, or |
| vectors. Either parentheses or braces form can be used. In the parentheses form |
| the number of literal values specified must be one, i.e. referring to a scalar |
| value, or must match the size of the vector type being created. If a single |
| scalar literal value is specified, the scalar literal value will be replicated |
| to all the components of the vector type. In the brackets form any number of |
| literals can be specified. For example:</p> |
| |
| <blockquote> |
| <pre> |
| typedef int v4si __attribute__((__vector_size__(16))); |
| typedef float float4 __attribute__((ext_vector_type(4))); |
| typedef float float2 __attribute__((ext_vector_type(2))); |
| |
| v4si vsi = (v4si){1, 2, 3, 4}; |
| float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f); |
| vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1). |
| vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0). |
| vector int vi3 = (vector int)(1, 2); // error |
| vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0). |
| vector int vi5 = (vector int)(1, 2, 3, 4); |
| float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f)); |
| </pre> |
| </blockquote> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="vector_operations">Vector Operations</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p>The table below shows the support for each operation by vector extension. |
| A dash indicates that an operation is not accepted according to a corresponding |
| specification.</p> |
| |
| <table width="500" border="1" cellspacing="0"> |
| <tr> |
| <th>Operator</th> |
| <th>OpenCL</th> |
| <th>AltiVec</th> |
| <th>GCC</th> |
| <th>NEON</th> |
| </tr> |
| <tr> |
| <td>[]</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">-</td> |
| </tr> |
| <tr> |
| <td>unary operators +, -</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">-</td> |
| </tr> |
| <tr> |
| <td>++, --</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">-</td> |
| <td align="center">-</td> |
| </tr> |
| <tr> |
| <td>+, -, *, /, %</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">-</td> |
| </tr> |
| <tr> |
| <td>bitwise operators &, |, ^, ~</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">-</td> |
| </tr> |
| <tr> |
| <td>>>, <<</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">-</td> |
| </tr> |
| <tr> |
| <td>!, &&,||</td> |
| <td align="center">no</td> |
| <td align="center">-</td> |
| <td align="center">-</td> |
| <td align="center">-</td> |
| </tr> |
| <tr> |
| <td>==,!=, >, <, >=, <=</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">-</td> |
| <td align="center">-</td> |
| </tr> |
| <tr> |
| <td>=</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| </tr> |
| <tr> |
| <td>:?</td> |
| <td align="center">yes</td> |
| <td align="center">-</td> |
| <td align="center">-</td> |
| <td align="center">-</td> |
| </tr> |
| <tr> |
| <td>sizeof</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| <td align="center">yes</td> |
| </tr> |
| </table> |
| |
| <p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2> |
| <!-- ======================================================================= --> |
| |
| <p>An optional string message can be added to the <tt>deprecated</tt> |
| and <tt>unavailable</tt> attributes. For example:</p> |
| |
| <blockquote> |
| <pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre> |
| </blockquote> |
| |
| <p>If the deprecated or unavailable declaration is used, the message |
| will be incorporated into the appropriate diagnostic:</p> |
| |
| <blockquote> |
| <pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! |
| [-Wdeprecated-declarations] |
| explode(); |
| ^</pre> |
| </blockquote> |
| |
| <p>Query for this feature |
| with <tt>__has_extension(attribute_deprecated_with_message)</tt> |
| and <tt>__has_extension(attribute_unavailable_with_message)</tt>.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="attributes-on-enumerators">Attributes on Enumerators</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang allows attributes to be written on individual enumerators. |
| This allows enumerators to be deprecated, made unavailable, etc. The |
| attribute must appear after the enumerator name and before any |
| initializer, like so:</p> |
| |
| <blockquote> |
| <pre>enum OperationMode { |
| OM_Invalid, |
| OM_Normal, |
| OM_Terrified __attribute__((deprecated)), |
| OM_AbortOnError __attribute__((deprecated)) = 4 |
| };</pre> |
| </blockquote> |
| |
| <p>Attributes on the <tt>enum</tt> declaration do not apply to |
| individual enumerators.</p> |
| |
| <p>Query for this feature with <tt>__has_extension(enumerator_attributes)</tt>.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="user_specified_system_framework">'User-Specified' System Frameworks</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang provides a mechanism by which frameworks can be built in such a way |
| that they will always be treated as being 'system frameworks', even if they are |
| not present in a system framework directory. This can be useful to system |
| framework developers who want to be able to test building other applications |
| with development builds of their framework, including the manner in which the |
| compiler changes warning behavior for system headers.</p> |
| |
| <p>Framework developers can opt-in to this mechanism by creating a |
| '.system_framework' file at the top-level of their framework. That is, the |
| framework should have contents like:</p> |
| |
| <pre> |
| .../TestFramework.framework |
| .../TestFramework.framework/.system_framework |
| .../TestFramework.framework/Headers |
| .../TestFramework.framework/Headers/TestFramework.h |
| ... |
| </pre> |
| |
| <p>Clang will treat the presence of this file as an indicator that the framework |
| should be treated as a system framework, regardless of how it was found in the |
| framework search path. For consistency, we recommend that such files never be |
| included in installed versions of the framework.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="availability">Availability attribute</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang introduces the <code>availability</code> attribute, which can |
| be placed on declarations to describe the lifecycle of that |
| declaration relative to operating system versions. Consider the function declaration for a hypothetical function <code>f</code>:</p> |
| |
| <pre> |
| void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7))); |
| </pre> |
| |
| <p>The availability attribute states that <code>f</code> was introduced in Mac OS X 10.4, deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information is used by Clang to determine when it is safe to use <code>f</code>: for example, if Clang is instructed to compile code for Mac OS X 10.5, a call to <code>f()</code> succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call succeeds but Clang emits a warning specifying that the function is deprecated. Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call fails because <code>f()</code> is no longer available.</p> |
| |
| <p>The availablility attribute is a comma-separated list starting with the platform name and then including clauses specifying important milestones in the declaration's lifetime (in any order) along with additional information. Those clauses can be:</p> |
| |
| <dl> |
| <dt>introduced=<i>version</i></dt> |
| <dd>The first version in which this declaration was introduced.</dd> |
| |
| <dt>deprecated=<i>version</i></dt> |
| <dd>The first version in which this declaration was deprecated, meaning that users should migrate away from this API.</dd> |
| |
| <dt>obsoleted=<i>version</i></dt> |
| <dd>The first version in which this declaration was obsoleted, meaning that it was removed completely and can no longer be used.</dd> |
| |
| <dt>unavailable</dt> |
| <dd>This declaration is never available on this platform.</dd> |
| |
| <dt>message=<i>string-literal</i></dt> |
| <dd>Additional message text that Clang will provide when emitting a warning or error about use of a deprecated or obsoleted declaration. Useful to direct users to replacement APIs.</dd> |
| </dl> |
| |
| <p>Multiple availability attributes can be placed on a declaration, which may correspond to different platforms. Only the availability attribute with the platform corresponding to the target platform will be used; any others will be ignored. If no availability attribute specifies availability for the current target platform, the availability attributes are ignored. Supported platforms are:</p> |
| |
| <dl> |
| <dt>ios</dt> |
| <dd>Apple's iOS operating system. The minimum deployment target is specified by the <code>-mios-version-min=<i>version</i></code> or <code>-miphoneos-version-min=<i>version</i></code> command-line arguments.</dd> |
| |
| <dt>macosx</dt> |
| <dd>Apple's Mac OS X operating system. The minimum deployment target is specified by the <code>-mmacosx-version-min=<i>version</i></code> command-line argument.</dd> |
| </dl> |
| |
| <p>A declaration can be used even when deploying back to a platform |
| version prior to when the declaration was introduced. When this |
| happens, the declaration is <a |
| href="https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html">weakly |
| linked</a>, as if the <code>weak_import</code> attribute were added to the declaration. A weakly-linked declaration may or may not be present a run-time, and a program can determine whether the declaration is present by checking whether the address of that declaration is non-NULL.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="checking_language_features">Checks for Standard Language Features</h2> |
| <!-- ======================================================================= --> |
| |
| <p>The <tt>__has_feature</tt> macro can be used to query if certain standard |
| language features are enabled. The <tt>__has_extension</tt> macro can be used |
| to query if language features are available as an extension when compiling for |
| a standard which does not provide them. The features which can be tested are |
| listed here.</p> |
| |
| <h3 id="cxx98">C++98</h3> |
| |
| <p>The features listed below are part of the C++98 standard. These features are |
| enabled by default when compiling C++ code.</p> |
| |
| <h4 id="cxx_exceptions">C++ exceptions</h4> |
| |
| <p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For |
| example, compiling code with <tt>-fno-exceptions</tt> disables C++ exceptions.</p> |
| |
| <h4 id="cxx_rtti">C++ RTTI</h4> |
| |
| <p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example, |
| compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p> |
| |
| <h3 id="cxx11">C++11</h3> |
| |
| <p>The features listed below are part of the C++11 standard. As a result, all |
| these features are enabled with the <tt>-std=c++11</tt> or <tt>-std=gnu++11</tt> |
| option when compiling C++ code.</p> |
| |
| <h4 id="cxx_access_control_sfinae">C++11 SFINAE includes access control</h4> |
| |
| <p>Use <tt>__has_feature(cxx_access_control_sfinae)</tt> or <tt>__has_extension(cxx_access_control_sfinae)</tt> to determine whether access-control errors (e.g., calling a private constructor) are considered to be template argument deduction errors (aka SFINAE errors), per <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170">C++ DR1170</a>.</p> |
| |
| <h4 id="cxx_alias_templates">C++11 alias templates</h4> |
| |
| <p>Use <tt>__has_feature(cxx_alias_templates)</tt> or |
| <tt>__has_extension(cxx_alias_templates)</tt> to determine if support for |
| C++11's alias declarations and alias templates is enabled.</p> |
| |
| <h4 id="cxx_alignas">C++11 alignment specifiers</h4> |
| |
| <p>Use <tt>__has_feature(cxx_alignas)</tt> or |
| <tt>__has_extension(cxx_alignas)</tt> to determine if support for alignment |
| specifiers using <tt>alignas</tt> is enabled.</p> |
| |
| <h4 id="cxx_attributes">C++11 attributes</h4> |
| |
| <p>Use <tt>__has_feature(cxx_attributes)</tt> or |
| <tt>__has_extension(cxx_attributes)</tt> to determine if support for attribute |
| parsing with C++11's square bracket notation is enabled.</p> |
| |
| <h4 id="cxx_constexpr">C++11 generalized constant expressions</h4> |
| |
| <p>Use <tt>__has_feature(cxx_constexpr)</tt> to determine if support |
| for generalized constant expressions (e.g., <tt>constexpr</tt>) is |
| enabled.</p> |
| |
| <h4 id="cxx_decltype">C++11 <tt>decltype()</tt></h4> |
| |
| <p>Use <tt>__has_feature(cxx_decltype)</tt> or |
| <tt>__has_extension(cxx_decltype)</tt> to determine if support for the |
| <tt>decltype()</tt> specifier is enabled. C++11's <tt>decltype</tt> |
| does not require type-completeness of a function call expression. |
| Use <tt>__has_feature(cxx_decltype_incomplete_return_types)</tt> |
| or <tt>__has_extension(cxx_decltype_incomplete_return_types)</tt> |
| to determine if support for this feature is enabled.</p> |
| |
| <h4 id="cxx_default_function_template_args">C++11 default template arguments in function templates</h4> |
| |
| <p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or |
| <tt>__has_extension(cxx_default_function_template_args)</tt> to determine |
| if support for default template arguments in function templates is enabled.</p> |
| |
| <h4 id="cxx_defaulted_functions">C++11 <tt>default</tt>ed functions</h4> |
| |
| <p>Use <tt>__has_feature(cxx_defaulted_functions)</tt> or |
| <tt>__has_extension(cxx_defaulted_functions)</tt> to determine if support for |
| defaulted function definitions (with <tt>= default</tt>) is enabled.</p> |
| |
| <h4 id="cxx_delegating_constructors">C++11 delegating constructors</h4> |
| |
| <p>Use <tt>__has_feature(cxx_delegating_constructors)</tt> to determine if |
| support for delegating constructors is enabled.</p> |
| |
| <h4 id="cxx_deleted_functions">C++11 <tt>delete</tt>d functions</h4> |
| |
| <p>Use <tt>__has_feature(cxx_deleted_functions)</tt> or |
| <tt>__has_extension(cxx_deleted_functions)</tt> to determine if support for |
| deleted function definitions (with <tt>= delete</tt>) is enabled.</p> |
| |
| <h4 id="cxx_explicit_conversions">C++11 explicit conversion functions</h4> |
| <p>Use <tt>__has_feature(cxx_explicit_conversions)</tt> to determine if support for <tt>explicit</tt> conversion functions is enabled.</p> |
| |
| <h4 id="cxx_generalized_initializers">C++11 generalized initializers</h4> |
| |
| <p>Use <tt>__has_feature(cxx_generalized_initializers)</tt> to determine if |
| support for generalized initializers (using braced lists and |
| <tt>std::initializer_list</tt>) is enabled.</p> |
| |
| <h4 id="cxx_implicit_moves">C++11 implicit move constructors/assignment operators</h4> |
| |
| <p>Use <tt>__has_feature(cxx_implicit_moves)</tt> to determine if Clang will |
| implicitly generate move constructors and move assignment operators where needed.</p> |
| |
| <h4 id="cxx_inheriting_constructors">C++11 inheriting constructors</h4> |
| |
| <p>Use <tt>__has_feature(cxx_inheriting_constructors)</tt> to determine if support for inheriting constructors is enabled. Clang does not currently implement this feature.</p> |
| |
| <h4 id="cxx_inline_namespaces">C++11 inline namespaces</h4> |
| |
| <p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> or |
| <tt>__has_extension(cxx_inline_namespaces)</tt> to determine if support for |
| inline namespaces is enabled.</p> |
| |
| <h4 id="cxx_lambdas">C++11 lambdas</h4> |
| |
| <p>Use <tt>__has_feature(cxx_lambdas)</tt> or |
| <tt>__has_extension(cxx_lambdas)</tt> to determine if support for lambdas |
| is enabled. </p> |
| |
| <h4 id="cxx_local_type_template_args">C++11 local and unnamed types as template arguments</h4> |
| |
| <p>Use <tt>__has_feature(cxx_local_type_template_args)</tt> or |
| <tt>__has_extension(cxx_local_type_template_args)</tt> to determine if |
| support for local and unnamed types as template arguments is enabled.</p> |
| |
| <h4 id="cxx_noexcept">C++11 noexcept</h4> |
| |
| <p>Use <tt>__has_feature(cxx_noexcept)</tt> or |
| <tt>__has_extension(cxx_noexcept)</tt> to determine if support for noexcept |
| exception specifications is enabled.</p> |
| |
| <h4 id="cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</h4> |
| |
| <p>Use <tt>__has_feature(cxx_nonstatic_member_init)</tt> to determine whether in-class initialization of non-static data members is enabled.</p> |
| |
| <h4 id="cxx_nullptr">C++11 <tt>nullptr</tt></h4> |
| |
| <p>Use <tt>__has_feature(cxx_nullptr)</tt> or |
| <tt>__has_extension(cxx_nullptr)</tt> to determine if support for |
| <tt>nullptr</tt> is enabled.</p> |
| |
| <h4 id="cxx_override_control">C++11 <tt>override control</tt></h4> |
| |
| <p>Use <tt>__has_feature(cxx_override_control)</tt> or |
| <tt>__has_extension(cxx_override_control)</tt> to determine if support for |
| the override control keywords is enabled.</p> |
| |
| <h4 id="cxx_reference_qualified_functions">C++11 reference-qualified functions</h4> |
| <p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> or |
| <tt>__has_extension(cxx_reference_qualified_functions)</tt> to determine |
| if support for reference-qualified functions (e.g., member functions with |
| <code>&</code> or <code>&&</code> applied to <code>*this</code>) |
| is enabled.</p> |
| |
| <h4 id="cxx_range_for">C++11 range-based <tt>for</tt> loop</h4> |
| |
| <p>Use <tt>__has_feature(cxx_range_for)</tt> or |
| <tt>__has_extension(cxx_range_for)</tt> to determine if support for the |
| range-based for loop is enabled. </p> |
| |
| <h4 id="cxx_raw_string_literals">C++11 raw string literals</h4> |
| <p>Use <tt>__has_feature(cxx_raw_string_literals)</tt> to determine if support |
| for raw string literals (e.g., <tt>R"x(foo\bar)x"</tt>) is enabled.</p> |
| |
| <h4 id="cxx_rvalue_references">C++11 rvalue references</h4> |
| |
| <p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or |
| <tt>__has_extension(cxx_rvalue_references)</tt> to determine if support for |
| rvalue references is enabled. </p> |
| |
| <h4 id="cxx_static_assert">C++11 <tt>static_assert()</tt></h4> |
| |
| <p>Use <tt>__has_feature(cxx_static_assert)</tt> or |
| <tt>__has_extension(cxx_static_assert)</tt> to determine if support for |
| compile-time assertions using <tt>static_assert</tt> is enabled.</p> |
| |
| <h4 id="cxx_auto_type">C++11 type inference</h4> |
| |
| <p>Use <tt>__has_feature(cxx_auto_type)</tt> or |
| <tt>__has_extension(cxx_auto_type)</tt> to determine C++11 type inference is |
| supported using the <tt>auto</tt> specifier. If this is disabled, <tt>auto</tt> |
| will instead be a storage class specifier, as in C or C++98.</p> |
| |
| <h4 id="cxx_strong_enums">C++11 strongly typed enumerations</h4> |
| |
| <p>Use <tt>__has_feature(cxx_strong_enums)</tt> or |
| <tt>__has_extension(cxx_strong_enums)</tt> to determine if support for |
| strongly typed, scoped enumerations is enabled.</p> |
| |
| <h4 id="cxx_trailing_return">C++11 trailing return type</h4> |
| |
| <p>Use <tt>__has_feature(cxx_trailing_return)</tt> or |
| <tt>__has_extension(cxx_trailing_return)</tt> to determine if support for the |
| alternate function declaration syntax with trailing return type is enabled.</p> |
| |
| <h4 id="cxx_unicode_literals">C++11 Unicode string literals</h4> |
| <p>Use <tt>__has_feature(cxx_unicode_literals)</tt> to determine if |
| support for Unicode string literals is enabled.</p> |
| |
| <h4 id="cxx_unrestricted_unions">C++11 unrestricted unions</h4> |
| |
| <p>Use <tt>__has_feature(cxx_unrestricted_unions)</tt> to determine if support for unrestricted unions is enabled.</p> |
| |
| <h4 id="cxx_user_literals">C++11 user-defined literals</h4> |
| |
| <p>Use <tt>__has_feature(cxx_user_literals)</tt> to determine if support for user-defined literals is enabled.</p> |
| |
| <h4 id="cxx_variadic_templates">C++11 variadic templates</h4> |
| |
| <p>Use <tt>__has_feature(cxx_variadic_templates)</tt> or |
| <tt>__has_extension(cxx_variadic_templates)</tt> to determine if support |
| for variadic templates is enabled.</p> |
| |
| <h3 id="c11">C11</h3> |
| |
| <p>The features listed below are part of the C11 standard. As a result, all |
| these features are enabled with the <tt>-std=c11</tt> or <tt>-std=gnu11</tt> |
| option when compiling C code. Additionally, because these features are all |
| backward-compatible, they are available as extensions in all language modes.</p> |
| |
| <h4 id="c_alignas">C11 alignment specifiers</h4> |
| |
| <p>Use <tt>__has_feature(c_alignas)</tt> or <tt>__has_extension(c_alignas)</tt> |
| to determine if support for alignment specifiers using <tt>_Alignas</tt> |
| is enabled.</p> |
| |
| <h4 id="c_atomic">C11 atomic operations</h4> |
| |
| <p>Use <tt>__has_feature(c_atomic)</tt> or <tt>__has_extension(c_atomic)</tt> |
| to determine if support for atomic types using <tt>_Atomic</tt> is enabled. |
| Clang also provides <a href="#__c11_atomic">a set of builtins</a> which can be |
| used to implement the <tt><stdatomic.h></tt> operations on |
| <tt>_Atomic</tt> types.</p> |
| |
| <h4 id="c_generic_selections">C11 generic selections</h4> |
| |
| <p>Use <tt>__has_feature(c_generic_selections)</tt> or |
| <tt>__has_extension(c_generic_selections)</tt> to determine if support for |
| generic selections is enabled.</p> |
| |
| <p>As an extension, the C11 generic selection expression is available in all |
| languages supported by Clang. The syntax is the same as that given in the |
| C11 standard.</p> |
| |
| <p>In C, type compatibility is decided according to the rules given in the |
| appropriate standard, but in C++, which lacks the type compatibility rules |
| used in C, types are considered compatible only if they are equivalent.</p> |
| |
| <h4 id="c_static_assert">C11 <tt>_Static_assert()</tt></h4> |
| |
| <p>Use <tt>__has_feature(c_static_assert)</tt> or |
| <tt>__has_extension(c_static_assert)</tt> to determine if support for |
| compile-time assertions using <tt>_Static_assert</tt> is enabled.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="checking_type_traits">Checks for Type Traits</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang supports the <a href="http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html">GNU C++ type traits</a> and a subset of the <a href="http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx">Microsoft Visual C++ Type traits</a>. For each supported type trait <code>__X</code>, <code>__has_extension(X)</code> indicates the presence of the type trait. For example: |
| <blockquote> |
| <pre> |
| #if __has_extension(is_convertible_to) |
| template<typename From, typename To> |
| struct is_convertible_to { |
| static const bool value = __is_convertible_to(From, To); |
| }; |
| #else |
| // Emulate type trait |
| #endif |
| </pre> |
| </blockquote> |
| |
| <p>The following type traits are supported by Clang:</p> |
| <ul> |
| <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li> |
| <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li> |
| <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li> |
| <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li> |
| <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li> |
| <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li> |
| <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li> |
| <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li> |
| <li><code>__is_abstract</code> (GNU, Microsoft)</li> |
| <li><code>__is_base_of</code> (GNU, Microsoft)</li> |
| <li><code>__is_class</code> (GNU, Microsoft)</li> |
| <li><code>__is_convertible_to</code> (Microsoft)</li> |
| <li><code>__is_empty</code> (GNU, Microsoft)</li> |
| <li><code>__is_enum</code> (GNU, Microsoft)</li> |
| <li><code>__is_pod</code> (GNU, Microsoft)</li> |
| <li><code>__is_polymorphic</code> (GNU, Microsoft)</li> |
| <li><code>__is_union</code> (GNU, Microsoft)</li> |
| <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li> |
| <li><code>__is_final</code>: Determines whether the given type is declared with a <code>final</code> class-virt-specifier.</li> |
| <li><code>__underlying_type(type)</code>: Retrieves the underlying type for a given <code>enum</code> type. This trait is required to implement the C++11 standard library.</li> |
| <li><code>__is_trivially_assignable(totype, fromtype)</code>: Determines whether a value of type <tt>totype</tt> can be assigned to from a value of type <tt>fromtype</tt> such that no non-trivial functions are called as part of that assignment. This trait is required to implement the C++11 standard library.</li> |
| <li><code>__is_trivially_constructible(type, argtypes...)</code>: Determines whether a value of type <tt>type</tt> can be direct-initialized with arguments of types <tt>argtypes...</tt> such that no non-trivial functions are called as part of that initialization. This trait is required to implement the C++11 standard library.</li> |
| </ul> |
| |
| <!-- ======================================================================= --> |
| <h2 id="blocks">Blocks</h2> |
| <!-- ======================================================================= --> |
| |
| <p>The syntax and high level language feature description is in <a |
| href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI |
| details for the clang implementation are in <a |
| href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p> |
| |
| |
| <p>Query for this feature with __has_extension(blocks).</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="objc_features">Objective-C Features</h2> |
| <!-- ======================================================================= --> |
| |
| <h3 id="objc_instancetype">Related result types</h3> |
| |
| <p>According to Cocoa conventions, Objective-C methods with certain names ("init", "alloc", etc.) always return objects that are an instance of the receiving class's type. Such methods are said to have a "related result type", meaning that a message send to one of these methods will have the same static type as an instance of the receiver class. For example, given the following classes:</p> |
| |
| <blockquote> |
| <pre> |
| @interface NSObject |
| + (id)alloc; |
| - (id)init; |
| @end |
| |
| @interface NSArray : NSObject |
| @end |
| </pre> |
| </blockquote> |
| |
| <p>and this common initialization pattern</p> |
| |
| <blockquote> |
| <pre> |
| NSArray *array = [[NSArray alloc] init]; |
| </pre> |
| </blockquote> |
| |
| <p>the type of the expression <code>[NSArray alloc]</code> is |
| <code>NSArray*</code> because <code>alloc</code> implicitly has a |
| related result type. Similarly, the type of the expression |
| <code>[[NSArray alloc] init]</code> is <code>NSArray*</code>, since |
| <code>init</code> has a related result type and its receiver is known |
| to have the type <code>NSArray *</code>. If neither <code>alloc</code> nor <code>init</code> had a related result type, the expressions would have had type <code>id</code>, as declared in the method signature.</p> |
| |
| <p>A method with a related result type can be declared by using the |
| type <tt>instancetype</tt> as its result type. <tt>instancetype</tt> |
| is a contextual keyword that is only permitted in the result type of |
| an Objective-C method, e.g.</p> |
| |
| <pre> |
| @interface A |
| + (<b>instancetype</b>)constructAnA; |
| @end |
| </pre> |
| |
| <p>The related result type can also be inferred for some methods. |
| To determine whether a method has an inferred related result type, the first |
| word in the camel-case selector (e.g., "init" in "initWithObjects") is |
| considered, and the method will have a related result type if its return |
| type is compatible with the type of its class and if</p> |
| |
| <ul> |
| |
| <li>the first word is "alloc" or "new", and the method is a class |
| method, or</li> |
| |
| <li>the first word is "autorelease", "init", "retain", or "self", |
| and the method is an instance method.</li> |
| |
| </ul> |
| |
| <p>If a method with a related result type is overridden by a subclass |
| method, the subclass method must also return a type that is compatible |
| with the subclass type. For example:</p> |
| |
| <blockquote> |
| <pre> |
| @interface NSString : NSObject |
| - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString |
| @end |
| </pre> |
| </blockquote> |
| |
| <p>Related result types only affect the type of a message send or |
| property access via the given method. In all other respects, a method |
| with a related result type is treated the same way as method that |
| returns <tt>id</tt>.</p> |
| |
| <p>Use <tt>__has_feature(objc_instancetype)</tt> to determine whether |
| the <tt>instancetype</tt> contextual keyword is available.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="objc_arc">Automatic reference counting </h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang provides support for <a href="AutomaticReferenceCounting.html">automated reference counting</a> in Objective-C, which eliminates the need for manual retain/release/autorelease message sends. There are two feature macros associated with automatic reference counting: <code>__has_feature(objc_arc)</code> indicates the availability of automated reference counting in general, while <code>__has_feature(objc_arc_weak)</code> indicates that automated reference counting also includes support for <code>__weak</code> pointers to Objective-C objects.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="objc_fixed_enum">Enumerations with a fixed underlying type</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang provides support for C++11 enumerations with a fixed |
| underlying type within Objective-C. For example, one can write an |
| enumeration type as:</p> |
| |
| <pre> |
| typedef enum : unsigned char { Red, Green, Blue } Color; |
| </pre> |
| |
| <p>This specifies that the underlying type, which is used to store the |
| enumeration value, is <tt>unsigned char</tt>.</p> |
| |
| <p>Use <tt>__has_feature(objc_fixed_enum)</tt> to determine whether |
| support for fixed underlying types is available in Objective-C.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="objc_lambdas">Interoperability with C++11 lambdas</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang provides interoperability between C++11 lambdas and |
| blocks-based APIs, by permitting a lambda to be implicitly converted |
| to a block pointer with the corresponding signature. For example, |
| consider an API such as <code>NSArray</code>'s array-sorting |
| method:</p> |
| |
| <pre> - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr; </pre> |
| |
| <p><code>NSComparator</code> is simply a typedef for the block pointer |
| <code>NSComparisonResult (^)(id, id)</code>, and parameters of this |
| type are generally provided with block literals as arguments. However, |
| one can also use a C++11 lambda so long as it provides the same |
| signature (in this case, accepting two parameters of type |
| <code>id</code> and returning an <code>NSComparisonResult</code>):</p> |
| |
| <pre> |
| NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11", |
| @"String 02"]; |
| const NSStringCompareOptions comparisonOptions |
| = NSCaseInsensitiveSearch | NSNumericSearch | |
| NSWidthInsensitiveSearch | NSForcedOrderingSearch; |
| NSLocale *currentLocale = [NSLocale currentLocale]; |
| NSArray *sorted |
| = [array sortedArrayUsingComparator:<b>[=](id s1, id s2) -> NSComparisonResult { |
| NSRange string1Range = NSMakeRange(0, [s1 length]); |
| return [s1 compare:s2 options:comparisonOptions |
| range:string1Range locale:currentLocale]; |
| }</b>]; |
| NSLog(@"sorted: %@", sorted); |
| </pre> |
| |
| <p>This code relies on an implicit conversion from the type of the |
| lambda expression (an unnamed, local class type called the <i>closure |
| type</i>) to the corresponding block pointer type. The conversion |
| itself is expressed by a conversion operator in that closure type |
| that produces a block pointer with the same signature as the lambda |
| itself, e.g.,</p> |
| |
| <pre> |
| operator NSComparisonResult (^)(id, id)() const; |
| </pre> |
| |
| <p>This conversion function returns a new block that simply forwards |
| the two parameters to the lambda object (which it captures by copy), |
| then returns the result. The returned block is first copied (with |
| <tt>Block_copy</tt>) and then autoreleased. As an optimization, if a |
| lambda expression is immediately converted to a block pointer (as in |
| the first example, above), then the block is not copied and |
| autoreleased: rather, it is given the same lifetime as a block literal |
| written at that point in the program, which avoids the overhead of |
| copying a block to the heap in the common case.</p> |
| |
| <p>The conversion from a lambda to a block pointer is only available |
| in Objective-C++, and not in C++ with blocks, due to its use of |
| Objective-C memory management (autorelease).</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="objc_object_literals_subscripting">Object Literals and Subscripting</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang provides support for <a href="ObjectiveCLiterals.html">Object Literals |
| and Subscripting</a> in Objective-C, which simplifies common Objective-C |
| programming patterns, makes programs more concise, and improves the safety of |
| container creation. There are several feature macros associated with object |
| literals and subscripting: <code>__has_feature(objc_array_literals)</code> |
| tests the availability of array literals; |
| <code>__has_feature(objc_dictionary_literals)</code> tests the availability of |
| dictionary literals; <code>__has_feature(objc_subscripting)</code> tests the |
| availability of object subscripting.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="objc_default_synthesize_properties">Objective-C Autosynthesis of Properties</h2> |
| <!-- ======================================================================= --> |
| |
| <p> Clang provides support for autosynthesis of declared properties. Using this |
| feature, clang provides default synthesis of those properties not declared @dynamic |
| and not having user provided backing getter and setter methods. |
| <code>__has_feature(objc_default_synthesize_properties)</code> checks for availability |
| of this feature in version of clang being used.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="overloading-in-c">Function Overloading in C</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang provides support for C++ function overloading in C. Function |
| overloading in C is introduced using the <tt>overloadable</tt> attribute. For |
| example, one might provide several overloaded versions of a <tt>tgsin</tt> |
| function that invokes the appropriate standard function computing the sine of a |
| value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt> |
| precision:</p> |
| |
| <blockquote> |
| <pre> |
| #include <math.h> |
| float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); } |
| double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); } |
| long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); } |
| </pre> |
| </blockquote> |
| |
| <p>Given these declarations, one can call <tt>tgsin</tt> with a |
| <tt>float</tt> value to receive a <tt>float</tt> result, with a |
| <tt>double</tt> to receive a <tt>double</tt> result, etc. Function |
| overloading in C follows the rules of C++ function overloading to pick |
| the best overload given the call arguments, with a few C-specific |
| semantics:</p> |
| <ul> |
| <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long |
| double</tt> is ranked as a floating-point promotion (per C99) rather |
| than as a floating-point conversion (as in C++).</li> |
| |
| <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type |
| <tt>U*</tt> is considered a pointer conversion (with conversion |
| rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li> |
| |
| <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt> |
| is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This |
| conversion is given "conversion" rank.</li> |
| </ul> |
| |
| <p>The declaration of <tt>overloadable</tt> functions is restricted to |
| function declarations and definitions. Most importantly, if any |
| function with a given name is given the <tt>overloadable</tt> |
| attribute, then all function declarations and definitions with that |
| name (and in that scope) must have the <tt>overloadable</tt> |
| attribute. This rule even applies to redeclarations of functions whose original |
| declaration had the <tt>overloadable</tt> attribute, e.g.,</p> |
| |
| <blockquote> |
| <pre> |
| int f(int) __attribute__((overloadable)); |
| float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i> |
| |
| int g(int) __attribute__((overloadable)); |
| int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i> |
| </pre> |
| </blockquote> |
| |
| <p>Functions marked <tt>overloadable</tt> must have |
| prototypes. Therefore, the following code is ill-formed:</p> |
| |
| <blockquote> |
| <pre> |
| int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i> |
| </pre> |
| </blockquote> |
| |
| <p>However, <tt>overloadable</tt> functions are allowed to use a |
| ellipsis even if there are no named parameters (as is permitted in C++). This feature is particularly useful when combined with the <tt>unavailable</tt> attribute:</p> |
| |
| <blockquote> |
| <pre> |
| void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i> |
| </pre> |
| </blockquote> |
| |
| <p>Functions declared with the <tt>overloadable</tt> attribute have |
| their names mangled according to the same rules as C++ function |
| names. For example, the three <tt>tgsin</tt> functions in our |
| motivating example get the mangled names <tt>_Z5tgsinf</tt>, |
| <tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two |
| caveats to this use of name mangling:</p> |
| |
| <ul> |
| |
| <li>Future versions of Clang may change the name mangling of |
| functions overloaded in C, so you should not depend on an specific |
| mangling. To be completely safe, we strongly urge the use of |
| <tt>static inline</tt> with <tt>overloadable</tt> functions.</li> |
| |
| <li>The <tt>overloadable</tt> attribute has almost no meaning when |
| used in C++, because names will already be mangled and functions are |
| already overloadable. However, when an <tt>overloadable</tt> |
| function occurs within an <tt>extern "C"</tt> linkage specification, |
| it's name <i>will</i> be mangled in the same way as it would in |
| C.</li> |
| </ul> |
| |
| <p>Query for this feature with __has_extension(attribute_overloadable).</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="complex-list-init">Initializer lists for complex numbers in C</h2> |
| <!-- ======================================================================= --> |
| |
| <p>clang supports an extension which allows the following in C:</p> |
| |
| <blockquote> |
| <pre> |
| #include <math.h> |
| #include <complex.h> |
| complex float x = { 1.0f, INFINITY }; // Init to (1, Inf) |
| </pre> |
| </blockquote> |
| |
| <p>This construct is useful because there is no way to separately |
| initialize the real and imaginary parts of a complex variable in |
| standard C, given that clang does not support <code>_Imaginary</code>. |
| (clang also supports the <code>__real__</code> and <code>__imag__</code> |
| extensions from gcc, which help in some cases, but are not usable in |
| static initializers.) |
| |
| <p>Note that this extension does not allow eliding the braces; the |
| meaning of the following two lines is different:</p> |
| |
| <blockquote> |
| <pre> |
| complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1) |
| complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0) |
| </pre> |
| </blockquote> |
| |
| <p>This extension also works in C++ mode, as far as that goes, but does not |
| apply to the C++ <code>std::complex</code>. (In C++11, list |
| initialization allows the same syntax to be used with |
| <code>std::complex</code> with the same meaning.) |
| |
| <!-- ======================================================================= --> |
| <h2 id="builtins">Builtin Functions</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang supports a number of builtin library functions with the same syntax as |
| GCC, including things like <tt>__builtin_nan</tt>, |
| <tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>, |
| <tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In |
| addition to the GCC builtins, Clang supports a number of builtins that GCC does |
| not, which are listed here.</p> |
| |
| <p>Please note that Clang does not and will not support all of the GCC builtins |
| for vector operations. Instead of using builtins, you should use the functions |
| defined in target-specific header files like <tt><xmmintrin.h></tt>, which |
| define portable wrappers for these. Many of the Clang versions of these |
| functions are implemented directly in terms of <a href="#vectors">extended |
| vector support</a> instead of builtins, in order to reduce the number of |
| builtins that we need to implement.</p> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__builtin_readcyclecounter">__builtin_readcyclecounter</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p><tt>__builtin_readcyclecounter</tt> is used to access the cycle counter |
| register (or a similar low-latency, high-accuracy clock) on those targets that |
| support it. |
| </p> |
| |
| <p><b>Syntax:</b></p> |
| |
| <pre> |
| __builtin_readcyclecounter() |
| </pre> |
| |
| <p><b>Example of Use:</b></p> |
| |
| <pre> |
| unsigned long long t0 = __builtin_readcyclecounter(); |
| do_something(); |
| unsigned long long t1 = __builtin_readcyclecounter(); |
| unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow |
| </pre> |
| |
| <p><b>Description:</b></p> |
| |
| <p>The __builtin_readcyclecounter() builtin returns the cycle counter value, |
| which may be either global or process/thread-specific depending on the target. |
| As the backing counters often overflow quickly (on the order of |
| seconds) this should only be used for timing small intervals. When not |
| supported by the target, the return value is always zero. This builtin |
| takes no arguments and produces an unsigned long long result. |
| </p> |
| |
| <p>Query for this feature with __has_builtin(__builtin_readcyclecounter).</p> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__builtin_shufflevector">__builtin_shufflevector</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p><tt>__builtin_shufflevector</tt> is used to express generic vector |
| permutation/shuffle/swizzle operations. This builtin is also very important for |
| the implementation of various target-specific header files like |
| <tt><xmmintrin.h></tt>. |
| </p> |
| |
| <p><b>Syntax:</b></p> |
| |
| <pre> |
| __builtin_shufflevector(vec1, vec2, index1, index2, ...) |
| </pre> |
| |
| <p><b>Examples:</b></p> |
| |
| <pre> |
| // Identity operation - return 4-element vector V1. |
| __builtin_shufflevector(V1, V1, 0, 1, 2, 3) |
| |
| // "Splat" element 0 of V1 into a 4-element result. |
| __builtin_shufflevector(V1, V1, 0, 0, 0, 0) |
| |
| // Reverse 4-element vector V1. |
| __builtin_shufflevector(V1, V1, 3, 2, 1, 0) |
| |
| // Concatenate every other element of 4-element vectors V1 and V2. |
| __builtin_shufflevector(V1, V2, 0, 2, 4, 6) |
| |
| // Concatenate every other element of 8-element vectors V1 and V2. |
| __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14) |
| </pre> |
| |
| <p><b>Description:</b></p> |
| |
| <p>The first two arguments to __builtin_shufflevector are vectors that have the |
| same element type. The remaining arguments are a list of integers that specify |
| the elements indices of the first two vectors that should be extracted and |
| returned in a new vector. These element indices are numbered sequentially |
| starting with the first vector, continuing into the second vector. Thus, if |
| vec1 is a 4-element vector, index 5 would refer to the second element of vec2. |
| </p> |
| |
| <p>The result of __builtin_shufflevector is a vector |
| with the same element type as vec1/vec2 but that has an element count equal to |
| the number of indices specified. |
| </p> |
| |
| <p>Query for this feature with __has_builtin(__builtin_shufflevector).</p> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__builtin_unreachable">__builtin_unreachable</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in |
| the program cannot be reached, even if the compiler might otherwise think it |
| can. This is useful to improve optimization and eliminates certain warnings. |
| For example, without the <tt>__builtin_unreachable</tt> in the example below, |
| the compiler assumes that the inline asm can fall through and prints a "function |
| declared 'noreturn' should not return" warning. |
| </p> |
| |
| <p><b>Syntax:</b></p> |
| |
| <pre> |
| __builtin_unreachable() |
| </pre> |
| |
| <p><b>Example of Use:</b></p> |
| |
| <pre> |
| void myabort(void) __attribute__((noreturn)); |
| void myabort(void) { |
| asm("int3"); |
| __builtin_unreachable(); |
| } |
| </pre> |
| |
| <p><b>Description:</b></p> |
| |
| <p>The __builtin_unreachable() builtin has completely undefined behavior. Since |
| it has undefined behavior, it is a statement that it is never reached and the |
| optimizer can take advantage of this to produce better code. This builtin takes |
| no arguments and produces a void result. |
| </p> |
| |
| <p>Query for this feature with __has_builtin(__builtin_unreachable).</p> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__sync_swap">__sync_swap</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in |
| memory. |
| </p> |
| |
| <p><b>Syntax:</b></p> |
| |
| <pre> |
| <i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...) |
| </pre> |
| |
| <p><b>Example of Use:</b></p> |
| |
| <pre> |
| int old_value = __sync_swap(&value, new_value); |
| </pre> |
| |
| <p><b>Description:</b></p> |
| |
| <p>The __sync_swap() builtin extends the existing __sync_*() family of atomic |
| intrinsics to allow code to atomically swap the current value with the new |
| value. More importantly, it helps developers write more efficient and correct |
| code by avoiding expensive loops around __sync_bool_compare_and_swap() or |
| relying on the platform specific implementation details of |
| __sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier. |
| </p> |
| |
| <!-- ======================================================================= --> |
| <h3><a name="__c11_atomic">__c11_atomic builtins</a></h3> |
| <!-- ======================================================================= --> |
| |
| <p>Clang provides a set of builtins which are intended to be used to implement |
| C11's <tt><stdatomic.h></tt> header. These builtins provide the semantics |
| of the <tt>_explicit</tt> form of the corresponding C11 operation, and are named |
| with a <tt>__c11_</tt> prefix. The supported operations are:</p> |
| |
| <ul> |
| <li><tt>__c11_atomic_init</tt></li> |
| <li><tt>__c11_atomic_thread_fence</tt></li> |
| <li><tt>__c11_atomic_signal_fence</tt></li> |
| <li><tt>__c11_atomic_is_lock_free</tt></li> |
| <li><tt>__c11_atomic_store</tt></li> |
| <li><tt>__c11_atomic_load</tt></li> |
| <li><tt>__c11_atomic_exchange</tt></li> |
| <li><tt>__c11_atomic_compare_exchange_strong</tt></li> |
| <li><tt>__c11_atomic_compare_exchange_weak</tt></li> |
| <li><tt>__c11_atomic_fetch_add</tt></li> |
| <li><tt>__c11_atomic_fetch_sub</tt></li> |
| <li><tt>__c11_atomic_fetch_and</tt></li> |
| <li><tt>__c11_atomic_fetch_or</tt></li> |
| <li><tt>__c11_atomic_fetch_xor</tt></li> |
| </ul> |
| |
| <!-- ======================================================================= --> |
| <h2 id="non-standard-attributes">Non-standard C++11 Attributes</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang supports one non-standard C++11 attribute. It resides in the |
| <tt>clang</tt> attribute namespace.</p> |
| |
| <!-- ======================================================================= --> |
| <h3 id="clang__fallthrough">The <tt>clang::fallthrough</tt> attribute</h3> |
| <!-- ======================================================================= --> |
| |
| <p>The <tt>clang::fallthrough</tt> attribute is used along with the |
| <tt>-Wimplicit-fallthrough</tt> argument to annotate intentional fall-through |
| between switch labels. It can only be applied to a null statement placed at a |
| point of execution between any statement and the next switch label. It is common |
| to mark these places with a specific comment, but this attribute is meant to |
| replace comments with a more strict annotation, which can be checked by the |
| compiler. This attribute doesn't change semantics of the code and can be used |
| wherever an intended fall-through occurs. It is designed to mimic |
| control-flow statements like <tt>break;</tt>, so it can be placed in most places |
| where <tt>break;</tt> can, but only if there are no statements on the execution |
| path between it and the next switch label.</p> |
| <p>Here is an example:</p> |
| <pre> |
| // compile with -Wimplicit-fallthrough |
| switch (n) { |
| case 22: |
| case 33: // no warning: no statements between case labels |
| f(); |
| case 44: // warning: unannotated fall-through |
| g(); |
| <b>[[clang::fallthrough]];</b> |
| case 55: // no warning |
| if (x) { |
| h(); |
| break; |
| } |
| else { |
| i(); |
| <b>[[clang::fallthrough]];</b> |
| } |
| case 66: // no warning |
| p(); |
| <b>[[clang::fallthrough]];</b> // warning: fallthrough annotation does not directly precede case label |
| q(); |
| case 77: // warning: unannotated fall-through |
| r(); |
| } |
| </pre> |
| |
| <!-- ======================================================================= --> |
| <h2 id="targetspecific">Target-Specific Extensions</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang supports some language features conditionally on some targets.</p> |
| |
| <!-- ======================================================================= --> |
| <h3 id="x86-specific">X86/X86-64 Language Extensions</h3> |
| <!-- ======================================================================= --> |
| |
| <p>The X86 backend has these language extensions:</p> |
| |
| <!-- ======================================================================= --> |
| <h4 id="x86-gs-segment">Memory references off the GS segment</h4> |
| <!-- ======================================================================= --> |
| |
| <p>Annotating a pointer with address space #256 causes it to be code generated |
| relative to the X86 GS segment register, and address space #257 causes it to be |
| relative to the X86 FS segment. Note that this is a very very low-level |
| feature that should only be used if you know what you're doing (for example in |
| an OS kernel).</p> |
| |
| <p>Here is an example:</p> |
| |
| <pre> |
| #define GS_RELATIVE __attribute__((address_space(256))) |
| int foo(int GS_RELATIVE *P) { |
| return *P; |
| } |
| </pre> |
| |
| <p>Which compiles to (on X86-32):</p> |
| |
| <pre> |
| _foo: |
| movl 4(%esp), %eax |
| movl %gs:(%eax), %eax |
| ret |
| </pre> |
| |
| <!-- ======================================================================= --> |
| <h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang supports additional attributes that are useful for documenting program |
| invariants and rules for static analysis tools. The extensions documented here |
| are used by the <a |
| href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer |
| engine</a> that is part of Clang's Analysis library.</p> |
| |
| <h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3> |
| |
| <p>Clang's static analysis engine understands the standard <tt>noreturn</tt> |
| attribute. This attribute, which is typically affixed to a function prototype, |
| indicates that a call to a given function never returns. Function prototypes for |
| common functions like <tt>exit</tt> are typically annotated with this attribute, |
| as well as a variety of common assertion handlers. Users can educate the static |
| analyzer about their own custom assertion handles (thus cutting down on false |
| positives due to false paths) by marking their own "panic" functions |
| with this attribute.</p> |
| |
| <p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes |
| there are special functions that for all intents and purposes should be |
| considered panic functions (i.e., they are only called when an internal program |
| error occurs) but may actually return so that the program can fail gracefully. |
| The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions |
| as being interpreted as "no return" functions by the analyzer (thus |
| pruning bogus paths) but will not affect compilation (as in the case of |
| <tt>noreturn</tt>).</p> |
| |
| <p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the |
| same places where the <tt>noreturn</tt> attribute can be placed. It is commonly |
| placed at the end of function prototypes:</p> |
| |
| <pre> |
| void foo() <b>__attribute__((analyzer_noreturn))</b>; |
| </pre> |
| |
| <p>Query for this feature with |
| <tt>__has_attribute(analyzer_noreturn)</tt>.</p> |
| |
| <h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3> |
| |
| <p>Many methods in Objective-C have conventional meanings determined |
| by their selectors. For the purposes of static analysis, it is |
| sometimes useful to be able to mark a method as having a particular |
| conventional meaning despite not having the right selector, or as not |
| having the conventional meaning that its selector would suggest. |
| For these use cases, we provide an attribute to specifically describe |
| the <q>method family</q> that a method belongs to.</p> |
| |
| <p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>, |
| where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>, |
| <tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>. This attribute |
| can only be placed at the end of a method declaration:</p> |
| |
| <pre> |
| - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>; |
| </pre> |
| |
| <p>Users who do not wish to change the conventional meaning of a |
| method, and who merely want to document its non-standard retain and |
| release semantics, should use the |
| <a href="#attr_retain_release">retaining behavior attributes</a> |
| described below.</p> |
| |
| <p>Query for this feature with |
| <tt>__has_attribute(objc_method_family)</tt>.</p> |
| |
| <h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3> |
| |
| <p>In Objective-C, functions and methods are generally assumed to take |
| and return objects with +0 retain counts, with some exceptions for |
| special methods like <tt>+alloc</tt> and <tt>init</tt>. However, |
| there are exceptions, and so Clang provides attributes to allow these |
| exceptions to be documented, which helps the analyzer find leaks (and |
| ignore non-leaks). Some exceptions may be better described using |
| the <a href="#attr_method_family"><tt>objc_method_family</tt></a> |
| attribute instead.</p> |
| |
| <p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>, |
| <tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>, |
| and <tt>cf_returns_not_retained</tt> attributes can be placed on |
| methods and functions that return Objective-C or CoreFoundation |
| objects. They are commonly placed at the end of a function prototype |
| or method declaration:</p> |
| |
| <pre> |
| id foo() <b>__attribute__((ns_returns_retained))</b>; |
| |
| - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>; |
| </pre> |
| |
| <p>The <tt>*_returns_retained</tt> attributes specify that the |
| returned object has a +1 retain count. |
| The <tt>*_returns_not_retained</tt> attributes specify that the return |
| object has a +0 retain count, even if the normal convention for its |
| selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the |
| returned object is +0, but is guaranteed to live at least as long as the |
| next flush of an autorelease pool.</p> |
| |
| <p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt> |
| attributes can be placed on an parameter declaration; they specify |
| that the argument is expected to have a +1 retain count, which will be |
| balanced in some way by the function or method. |
| The <tt>ns_consumes_self</tt> attribute can only be placed on an |
| Objective-C method; it specifies that the method expects |
| its <tt>self</tt> parameter to have a +1 retain count, which it will |
| balance in some way.</p> |
| |
| <pre> |
| void <b>foo(__attribute__((ns_consumed))</b> NSString *string); |
| |
| - (void) bar <b>__attribute__((ns_consumes_self))</b>; |
| - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x; |
| </pre> |
| |
| <p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>, |
| <tt>__has_attribute(ns_returns_retained)</tt>, etc.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</h2> |
| <!-- ======================================================================= --> |
| <h3 id="address_sanitizer">AddressSanitizer</h3> |
| <p> Use <code>__has_feature(address_sanitizer)</code> |
| to check if the code is being built with <a |
| href="AddressSanitizer.html">AddressSanitizer</a>. |
| </p> |
| <p>Use <tt>__attribute__((no_address_safety_analysis))</tt> on a function |
| declaration to specify that address safety instrumentation (e.g. |
| AddressSanitizer) should not be applied to that function. |
| </p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="threadsafety">Thread-Safety Annotation Checking</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang supports additional attributes for checking basic locking policies in |
| multithreaded programs. |
| Clang currently parses the following list of attributes, although |
| <b>the implementation for these annotations is currently in development.</b> |
| For more details, see the |
| <a href="http://gcc.gnu.org/wiki/ThreadSafetyAnnotation">GCC implementation</a>. |
| </p> |
| |
| <h4 id="ts_noanal">no_thread_safety_analysis</h4> |
| |
| <p>Use <tt>__attribute__((no_thread_safety_analysis))</tt> on a function |
| declaration to specify that the thread safety analysis should not be run on that |
| function. This attribute provides an escape hatch (e.g. for situations when it |
| is difficult to annotate the locking policy). </p> |
| |
| <h4 id="ts_lockable">lockable</h4> |
| |
| <p>Use <tt>__attribute__((lockable))</tt> on a class definition to specify |
| that it has a lockable type (e.g. a Mutex class). This annotation is primarily |
| used to check consistency.</p> |
| |
| <h4 id="ts_scopedlockable">scoped_lockable</h4> |
| |
| <p>Use <tt>__attribute__((scoped_lockable))</tt> on a class definition to |
| specify that it has a "scoped" lockable type. Objects of this type will acquire |
| the lock upon construction and release it upon going out of scope. |
| This annotation is primarily used to check |
| consistency.</p> |
| |
| <h4 id="ts_guardedvar">guarded_var</h4> |
| |
| <p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to |
| specify that the variable must be accessed while holding some lock.</p> |
| |
| <h4 id="ts_ptguardedvar">pt_guarded_var</h4> |
| |
| <p>Use <tt>__attribute__((pt_guarded_var))</tt> on a pointer declaration to |
| specify that the pointer must be dereferenced while holding some lock.</p> |
| |
| <h4 id="ts_guardedby">guarded_by(l)</h4> |
| |
| <p>Use <tt>__attribute__((guarded_by(l)))</tt> on a variable declaration to |
| specify that the variable must be accessed while holding lock <tt>l</tt>.</p> |
| |
| <h4 id="ts_ptguardedby">pt_guarded_by(l)</h4> |
| |
| <p>Use <tt>__attribute__((pt_guarded_by(l)))</tt> on a pointer declaration to |
| specify that the pointer must be dereferenced while holding lock <tt>l</tt>.</p> |
| |
| <h4 id="ts_acquiredbefore">acquired_before(...)</h4> |
| |
| <p>Use <tt>__attribute__((acquired_before(...)))</tt> on a declaration |
| of a lockable variable to specify that the lock must be acquired before all |
| attribute arguments. Arguments must be lockable type, and there must be at |
| least one argument.</p> |
| |
| <h4 id="ts_acquiredafter">acquired_after(...)</h4> |
| |
| <p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration |
| of a lockable variable to specify that the lock must be acquired after all |
| attribute arguments. Arguments must be lockable type, and there must be at |
| least one argument.</p> |
| |
| <h4 id="ts_elf">exclusive_lock_function(...)</h4> |
| |
| <p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function |
| declaration to specify that the function acquires all listed locks |
| exclusively. This attribute takes zero or more arguments: either of lockable |
| type or integers indexing into function parameters of lockable type. If no |
| arguments are given, the acquired lock is implicitly <tt>this</tt> of the |
| enclosing object.</p> |
| |
| <h4 id="ts_slf">shared_lock_function(...)</h4> |
| |
| <p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function |
| declaration to specify that the function acquires all listed locks, although |
| the locks may be shared (e.g. read locks). This attribute takes zero or more |
| arguments: either of lockable type or integers indexing into function |
| parameters of lockable type. If no arguments are given, the acquired lock is |
| implicitly <tt>this</tt> of the enclosing object.</p> |
| |
| <h4 id="ts_etf">exclusive_trylock_function(...)</h4> |
| |
| <p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function |
| declaration to specify that the function will try (without blocking) to acquire |
| all listed locks exclusively. This attribute takes one or more arguments. The |
| first argument is an integer or boolean value specifying the return value of a |
| successful lock acquisition. The remaining arugments are either of lockable type |
| or integers indexing into function parameters of lockable type. If only one |
| argument is given, the acquired lock is implicitly <tt>this</tt> of the |
| enclosing object.</p> |
| |
| <h4 id="ts_stf">shared_trylock_function(...)</h4> |
| |
| <p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function |
| declaration to specify that the function will try (without blocking) to acquire |
| all listed locks, although the locks may be shared (e.g. read locks). This |
| attribute takes one or more arguments. The first argument is an integer or |
| boolean value specifying the return value of a successful lock acquisition. The |
| remaining arugments are either of lockable type or integers indexing into |
| function parameters of lockable type. If only one argument is given, the |
| acquired lock is implicitly <tt>this</tt> of the enclosing object.</p> |
| |
| <h4 id="ts_uf">unlock_function(...)</h4> |
| |
| <p>Use <tt>__attribute__((unlock_function(...)))</tt> on a function |
| declaration to specify that the function release all listed locks. This |
| attribute takes zero or more arguments: either of lockable type or integers |
| indexing into function parameters of lockable type. If no arguments are given, |
| the acquired lock is implicitly <tt>this</tt> of the enclosing object.</p> |
| |
| <h4 id="ts_lr">lock_returned(l)</h4> |
| |
| <p>Use <tt>__attribute__((lock_returned(l)))</tt> on a function |
| declaration to specify that the function returns lock <tt>l</tt> (<tt>l</tt> |
| must be of lockable type). This annotation is used to aid in resolving lock |
| expressions.</p> |
| |
| <h4 id="ts_le">locks_excluded(...)</h4> |
| |
| <p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration |
| to specify that the function must not be called with the listed locks. Arguments |
| must be lockable type, and there must be at least one argument.</p> |
| |
| <h4 id="ts_elr">exclusive_locks_required(...)</h4> |
| |
| <p>Use <tt>__attribute__((exclusive_locks_required(...)))</tt> on a function |
| declaration to specify that the function must be called while holding the listed |
| exclusive locks. Arguments must be lockable type, and there must be at |
| least one argument.</p> |
| |
| <h4 id="ts_slr">shared_locks_required(...)</h4> |
| |
| <p>Use <tt>__attribute__((shared_locks_required(...)))</tt> on a function |
| declaration to specify that the function must be called while holding the listed |
| shared locks. Arguments must be lockable type, and there must be at |
| least one argument.</p> |
| |
| <!-- ======================================================================= --> |
| <h2 id="type_safety">Type Safety Checking</h2> |
| <!-- ======================================================================= --> |
| |
| <p>Clang supports additional attributes to enable checking type safety |
| properties that can't be enforced by C type system. Usecases include:</p> |
| <ul> |
| <li>MPI library implementations, where these attributes enable checking that |
| buffer type matches the passed <tt>MPI_Datatype</tt>;</li> |
| <li>for HDF5 library there is a similar usecase as MPI;</li> |
| <li>checking types of variadic functions' arguments for functions like |
| <tt>fcntl()</tt> and <tt>ioctl()</tt>.</li> |
| </ul> |
| |
| <p>You can detect support for these attributes with __has_attribute(). For |
| example:</p> |
| |
| <blockquote> |
| <pre> |
| #if defined(__has_attribute) |
| # if __has_attribute(argument_with_type_tag) && \ |
| __has_attribute(pointer_with_type_tag) && \ |
| __has_attribute(type_tag_for_datatype) |
| # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx))) |
| /* ... other macros ... */ |
| # endif |
| #endif |
| |
| #if !defined(ATTR_MPI_PWT) |
| #define ATTR_MPI_PWT(buffer_idx, type_idx) |
| #endif |
| |
| int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) |
| ATTR_MPI_PWT(1,3); |
| </pre> |
| </blockquote> |
| |
| <h3 id="argument_with_type_tag"><tt>argument_with_type_tag(...)</tt></h3> |
| |
| <p>Use <tt>__attribute__((argument_with_type_tag(arg_kind, arg_idx, |
| type_tag_idx)))</tt> on a function declaration to specify that the function |
| accepts a type tag that determines the type of some other argument. |
| <tt>arg_kind</tt> is an identifier that should be used when annotating all |
| applicable type tags.</p> |
| |
| <p>This attribute is primarily useful for checking arguments of variadic |
| functions (<tt>pointer_with_type_tag</tt> can be used in most of non-variadic |
| cases).</p> |
| |
| <p>For example:</p> |
| <blockquote> |
| <pre> |
| int fcntl(int fd, int cmd, ...) |
| __attribute__(( argument_with_type_tag(fcntl,3,2) )); |
| </pre> |
| </blockquote> |
| |
| <h3 id="pointer_with_type_tag"><tt>pointer_with_type_tag(...)</tt></h3> |
| |
| <p>Use <tt>__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, |
| type_tag_idx)))</tt> on a function declaration to specify that the |
| function accepts a type tag that determines the pointee type of some other |
| pointer argument.</p> |
| |
| <p>For example:</p> |
| <blockquote> |
| <pre> |
| int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) |
| __attribute__(( pointer_with_type_tag(mpi,1,3) )); |
| </pre> |
| </blockquote> |
| |
| <h3 id="type_tag_for_datatype"><tt>type_tag_for_datatype(...)</tt></h3> |
| |
| <p>Clang supports annotating type tags of two forms.</p> |
| |
| <ul> |
| <li><b>Type tag that is an expression containing a reference to some declared |
| identifier.</b> Use <tt>__attribute__((type_tag_for_datatype(kind, type)))</tt> |
| on a declaration with that identifier: |
| |
| <blockquote> |
| <pre> |
| extern struct mpi_datatype mpi_datatype_int |
| __attribute__(( type_tag_for_datatype(mpi,int) )); |
| #define MPI_INT ((MPI_Datatype) &mpi_datatype_int) |
| </pre> |
| </blockquote></li> |
| |
| <li><b>Type tag that is an integral literal.</b> Introduce a <tt>static |
| const</tt> variable with a corresponding initializer value and attach |
| <tt>__attribute__((type_tag_for_datatype(kind, type)))</tt> on that |
| declaration, for example: |
| |
| <blockquote> |
| <pre> |
| #define MPI_INT ((MPI_Datatype) 42) |
| static const MPI_Datatype mpi_datatype_int |
| __attribute__(( type_tag_for_datatype(mpi,int) )) = 42 |
| </pre> |
| </blockquote></li> |
| </ul> |
| |
| <p>The attribute also accepts an optional third argument that determines how |
| the expression is compared to the type tag. There are two supported flags:</p> |
| |
| <ul><li><tt>layout_compatible</tt> will cause types to be compared according to |
| layout-compatibility rules (C++11 [class.mem] p 17, 18). This is |
| implemented to support annotating types like <tt>MPI_DOUBLE_INT</tt>. |
| |
| <p>For example:</p> |
| <blockquote> |
| <pre> |
| /* In mpi.h */ |
| struct internal_mpi_double_int { double d; int i; }; |
| extern struct mpi_datatype mpi_datatype_double_int |
| __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, |
| layout_compatible) )); |
| |
| #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int) |
| |
| /* In user code */ |
| struct my_pair { double a; int b; }; |
| struct my_pair *buffer; |
| MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning |
| |
| struct my_int_pair { int a; int b; } |
| struct my_int_pair *buffer2; |
| MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element |
| // type 'struct my_int_pair' |
| // doesn't match specified MPI_Datatype |
| </pre> |
| </blockquote> |
| </li> |
| |
| <li><tt>must_be_null</tt> specifies that the expression should be a null |
| pointer constant, for example: |
| |
| <blockquote> |
| <pre> |
| /* In mpi.h */ |
| extern struct mpi_datatype mpi_datatype_null |
| __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) )); |
| |
| #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null) |
| |
| /* In user code */ |
| MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL |
| // was specified but buffer |
| // is not a null pointer |
| </pre> |
| </blockquote> |
| </li> |
| </ul> |
| |
| </div> |
| </body> |
| </html> |