Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / ece3894a9fe3ce3d282e63c349d84c0923143fe2 / . / docs / LanguageExtensions.html
blob: b621eab311f6de83fa5d3741c37274ba9d6cb25c [file] [log] [blame]
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]4<html>
5<head>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]6 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7 <title>Clang LanguageExtensions</title>
Sean Hunt64f857b2011-06-23 01:22:53 +0000[diff] [blame]8 <link type="text/css" rel="stylesheet" href="../menu.css">
9 <link type="text/css" rel="stylesheet" href="../content.css">
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]10 <style type="text/css">
11 td {
12 vertical-align: top;
13 }
14 </style>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]15</head>
16<body>
17
18<!--#include virtual="../menu.html.incl"-->
19
20<div id="content">
21
22<h1>Clang Language Extensions</h1>
23
24<ul>
25<li><a href="#intro">Introduction</a></li>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]26<li><a href="#feature_check">Feature Checking Macros</a></li>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]27<li><a href="#has_include">Include File Checking Macros</a></li>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]28<li><a href="#builtinmacros">Builtin Macros</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]29<li><a href="#vectors">Vectors and Extended Vectors</a></li>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]30<li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li>
31<li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]32<li><a href="#checking_language_features">Checks for Standard Language Features</a>
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]33 <ul>
34 <li><a href="#cxx_exceptions">C++ exceptions</a></li>
35 <li><a href="#cxx_rtti">C++ RTTI</a></li>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]36 </ul></li>
37<li><a href="#checking_upcoming_features">Checks for Upcoming Standard Language Features</a>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]38 <ul>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]39 <li><a href="#cxx0x">C++0x</a>
40 <ul>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]41 <li><a href="#cxx_access_control_sfinae">C++0x SFINAE includes access control</a></li>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]42 <li><a href="#cxx_alias_templates">C++0x alias templates</a></li>
43 <li><a href="#cxx_attributes">C++0x attributes</a></li>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]44 <li><a href="#cxx_constexpr">C++0x generalized constant expressions</a></li>
45 <li><a href="#cxx_decltype">C++0x <tt>decltype()</tt></a></li>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]46 <li><a href="#cxx_default_function_template_args">C++0x default template arguments in function templates</a></li>
Sean Huntd9624992011-06-23 06:11:37 +0000[diff] [blame]47 <li><a href="#cxx_delegating_constructor">C++0x delegating constructors</a></li>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]48 <li><a href="#cxx_deleted_functions">C++0x deleted functions</a></li>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]49 <li><a href="#cxx_explicit_conversions">C++0x explicit conversion functions</a></li>
Sean Hunte1f6dea2011-08-07 00:34:32 +0000[diff] [blame]50 <li><a href="#cxx_generalized_initializers">C++0x generalized initializers</a></li>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]51 <li><a href="#cxx_implicit_moves">C++0x implicit move constructors/assignment operators</a></li>
52 <li><a href="#cxx_inheriting_constructors">C++0x inheriting constructors</a></li>
53 <li><a href="#cxx_inline_namespaces">C++0x inline namespaces</a></li>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]54 <li><a href="#cxx_lambdas">C++0x lambdas</a></li>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]55 <li><a href="#cxx_noexcept">C++0x noexcept specification</a></li>
56 <li><a href="#cxx_nonstatic_member_init">C++0x in-class non-static data member initialization</a></li>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]57 <li><a href="#cxx_nullptr">C++0x nullptr</a></li>
58 <li><a href="#cxx_override_control">C++0x override control</a></li>
59 <li><a href="#cxx_range_for">C++0x range-based for loop</a></li>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]60 <li><a href="#cxx_raw_string_literals">C++0x raw string literals</a></li>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]61 <li><a href="#cxx_rvalue_references">C++0x rvalue references</a></li>
62 <li><a href="#cxx_reference_qualified_functions">C++0x reference-qualified functions</a></li>
63 <li><a href="#cxx_static_assert">C++0x <tt>static_assert()</tt></a></li>
64 <li><a href="#cxx_auto_type">C++0x type inference</a></li>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]65 <li><a href="#cxx_strong_enums">C++0x strongly-typed enumerations</a></li>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]66 <li><a href="#cxx_trailing_return">C++0x trailing return type</a></li>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]67 <li><a href="#cxx_unicode_literals">C++0x Unicode string literals</a></li>
68 <li><a href="#cxx_unrestricted_unions">C++0x unrestricted unions</a></li>
69 <li><a href="#cxx_user_literals">C++0x user-defined literals</a></li>
70 <li><a href="#cxx_variadic_templates">C++0x variadic templates</a></li>
71 </ul></li>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]72 <li><a href="#c1x">C1X</a>
73 <ul>
74 <li><a href="#c_generic_selections">C1X generic selections</a></li>
75 <li><a href="#c_static_assert">C1X <tt>_Static_assert()</tt></a></li>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]76 </ul></li>
77 </ul> </li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]78<li><a href="#checking_type_traits">Checks for Type Traits</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]79<li><a href="#blocks">Blocks</a></li>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]80<li><a href="#objc_features">Objective-C Features</a>
81 <ul>
82 <li><a href="#objc_instancetype">Related result types</a></li>
John McCallf85e1932011-06-15 23:02:42 +0000[diff] [blame]83 <li><a href="#objc_arc">Automatic reference counting</a></li>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]84 </ul>
85</li>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]86<li><a href="#overloading-in-c">Function Overloading in C</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]87<li><a href="#builtins">Builtin Functions</a>
88 <ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]89 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]90 <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li>
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]91 <li><a href="#__sync_swap">__sync_swap</a></li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]92 </ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]93</li>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]94<li><a href="#targetspecific">Target-Specific Extensions</a>
95 <ul>
96 <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li>
97 </ul>
98</li>
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]99<li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]100<li><a href="#threadsafety">Thread Safety Annotation Checking</a></li>
101 <ul>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]102 <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li>
103 <li><a href="#ts_lockable"><tt>lockable</tt></a></li>
104 <li><a href="#ts_scopedlockable"><tt>scoped_lockable</tt></a></li>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]105 <li><a href="#ts_guardedvar"><tt>guarded_var</tt></a></li>
106 <li><a href="#ts_ptguardedvar"><tt>pt_guarded_var</tt></a></li>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]107 <li><a href="#ts_guardedby"><tt>guarded_by(l)</tt></a></li>
108 <li><a href="#ts_ptguardedby"><tt>pt_guarded_by(l)</tt></a></li>
109 <li><a href="#ts_acquiredbefore"><tt>acquired_before(...)</tt></a></li>
110 <li><a href="#ts_acquiredafter"><tt>acquired_after(...)</tt></a></li>
111 <li><a href="#ts_elf"><tt>exclusive_lock_function(...)</tt></a></li>
112 <li><a href="#ts_slf"><tt>shared_lock_function(...)</tt></a></li>
113 <li><a href="#ts_etf"><tt>exclusive_trylock_function(...)</tt></a></li>
114 <li><a href="#ts_stf"><tt>shared_trylock_function(...)</tt></a></li>
115 <li><a href="#ts_uf"><tt>unlock_function(...)</tt></a></li>
116 <li><a href="#ts_lr"><tt>lock_returned(l)</tt></a></li>
117 <li><a href="#ts_le"><tt>locks_excluded(...)</tt></a></li>
118 <li><a href="#ts_elr"><tt>exclusive_locks_required(...)</tt></a></li>
119 <li><a href="#ts_slr"><tt>shared_locks_required(...)</tt></a></li>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]120 </ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]121</ul>
122
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]123<!-- ======================================================================= -->
124<h2 id="intro">Introduction</h2>
125<!-- ======================================================================= -->
126
127<p>This document describes the language extensions provided by Clang. In
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]128addition to the language extensions listed here, Clang aims to support a broad
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]129range of GCC extensions. Please see the <a
130href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
131more information on these extensions.</p>
132
133<!-- ======================================================================= -->
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]134<h2 id="feature_check">Feature Checking Macros</h2>
135<!-- ======================================================================= -->
136
137<p>Language extensions can be very useful, but only if you know you can depend
Chris Lattnerc70e1932011-03-21 16:25:11 +0000[diff] [blame]138on them. In order to allow fine-grain features checks, we support three builtin
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]139function-like macros. This allows you to directly test for a feature in your
140code without having to resort to something like autoconf or fragile "compiler
141version checks".</p>
142
143<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]144<h3><a name="__has_builtin">__has_builtin</a></h3>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]145<!-- ======================================================================= -->
146
147<p>This function-like macro takes a single identifier argument that is the name
148of a builtin function. It evaluates to 1 if the builtin is supported or 0 if
149not. It can be used like this:</p>
150
151<blockquote>
152<pre>
153#ifndef __has_builtin // Optional of course.
154 #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
155#endif
156
157...
158#if __has_builtin(__builtin_trap)
159 __builtin_trap();
160#else
161 abort();
162#endif
163...
164</pre>
165</blockquote>
166
167
168<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]169<h3><a name="__has_feature_extension"> __has_feature and __has_extension</a></h3>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]170<!-- ======================================================================= -->
171
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]172<p>These function-like macros take a single identifier argument that is the
173name of a feature. <code>__has_feature</code> evaluates to 1 if the feature
174is both supported by Clang and standardized in the current language standard
175or 0 if not (but see <a href="#has_feature_back_compat">below</a>), while
176<code>__has_extension</code> evaluates to 1 if the feature is supported by
177Clang in the current language (either as a language extension or a standard
178language feature) or 0 if not. They can be used like this:</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]179
180<blockquote>
181<pre>
182#ifndef __has_feature // Optional of course.
183 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
184#endif
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]185#ifndef __has_extension
186 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
187#endif
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]188
189...
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]190#if __has_feature(cxx_rvalue_references)
191// This code will only be compiled with the -std=c++0x and -std=gnu++0x
192// options, because rvalue references are only standardized in C++0x.
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]193#endif
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]194
195#if __has_extension(cxx_rvalue_references)
196// This code will be compiled with the -std=c++0x, -std=gnu++0x, -std=c++98
197// and -std=gnu++98 options, because rvalue references are supported as a
198// language extension in C++98.
199#endif
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]200</pre>
201</blockquote>
202
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]203<p id="has_feature_back_compat">For backwards compatibility reasons,
204<code>__has_feature</code> can also be used to test for support for
205non-standardized features, i.e. features not prefixed <code>c_</code>,
206<code>cxx_</code> or <code>objc_</code>.</p>
207
208<p>If the <code>-pedantic-errors</code> option is given,
209<code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p>
210
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]211<p>The feature tag is described along with the language feature below.</p>
212
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]213<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]214<h3><a name="__has_attribute">__has_attribute</a></h3>
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]215<!-- ======================================================================= -->
216
217<p>This function-like macro takes a single identifier argument that is the name
218of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It
219can be used like this:</p>
220
221<blockquote>
222<pre>
223#ifndef __has_attribute // Optional of course.
224 #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
225#endif
226
227...
Anders Carlsson961003d2011-01-24 03:54:51 +0000[diff] [blame]228#if __has_attribute(always_inline)
229#define ALWAYS_INLINE __attribute__((always_inline))
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]230#else
Anders Carlsson961003d2011-01-24 03:54:51 +0000[diff] [blame]231#define ALWAYS_INLINE
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]232#endif
233...
234</pre>
235</blockquote>
236
237<!-- ======================================================================= -->
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]238<h2 id="has_include">Include File Checking Macros</h2>
239<!-- ======================================================================= -->
240
241<p>Not all developments systems have the same include files.
242The <a href="#__has_include">__has_include</a> and
243<a href="#__has_include_next">__has_include_next</a> macros allow you to
244check for the existence of an include file before doing
245a possibly failing #include directive.</p>
246
247<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]248<h3><a name="__has_include">__has_include</a></h3>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]249<!-- ======================================================================= -->
250
251<p>This function-like macro takes a single file name string argument that
252is the name of an include file. It evaluates to 1 if the file can
253be found using the include paths, or 0 otherwise:</p>
254
255<blockquote>
256<pre>
257// Note the two possible file name string formats.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]258#if __has_include("myinclude.h") &amp;&amp; __has_include(&lt;stdint.h&gt;)
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]259# include "myinclude.h"
260#endif
261
262// To avoid problem with non-clang compilers not having this macro.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]263#if defined(__has_include) &amp;&amp; __has_include("myinclude.h")
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]264# include "myinclude.h"
265#endif
266</pre>
267</blockquote>
268
269<p>To test for this feature, use #if defined(__has_include).</p>
270
271<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]272<h3><a name="__has_include_next">__has_include_next</a></h3>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]273<!-- ======================================================================= -->
274
275<p>This function-like macro takes a single file name string argument that
276is the name of an include file. It is like __has_include except that it
277looks for the second instance of the given file found in the include
278paths. It evaluates to 1 if the second instance of the file can
279be found using the include paths, or 0 otherwise:</p>
280
281<blockquote>
282<pre>
283// Note the two possible file name string formats.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]284#if __has_include_next("myinclude.h") &amp;&amp; __has_include_next(&lt;stdint.h&gt;)
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]285# include_next "myinclude.h"
286#endif
287
288// To avoid problem with non-clang compilers not having this macro.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]289#if defined(__has_include_next) &amp;&amp; __has_include_next("myinclude.h")
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]290# include_next "myinclude.h"
291#endif
292</pre>
293</blockquote>
294
295<p>Note that __has_include_next, like the GNU extension
296#include_next directive, is intended for use in headers only,
297and will issue a warning if used in the top-level compilation
298file. A warning will also be issued if an absolute path
299is used in the file argument.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]300
301<!-- ======================================================================= -->
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]302<h2 id="builtinmacros">Builtin Macros</h2>
303<!-- ======================================================================= -->
304
Douglas Gregor4290fbd2010-04-30 02:51:06 +0000[diff] [blame]305<dl>
306 <dt><code>__BASE_FILE__</code></dt>
307 <dd>Defined to a string that contains the name of the main input
308 file passed to Clang.</dd>
309
310 <dt><code>__COUNTER__</code></dt>
311 <dd>Defined to an integer value that starts at zero and is
312 incremented each time the <code>__COUNTER__</code> macro is
313 expanded.</dd>
314
315 <dt><code>__INCLUDE_LEVEL__</code></dt>
316 <dd>Defined to an integral value that is the include depth of the
317 file currently being translated. For the main file, this value is
318 zero.</dd>
319
320 <dt><code>__TIMESTAMP__</code></dt>
321 <dd>Defined to the date and time of the last modification of the
322 current source file.</dd>
323
324 <dt><code>__clang__</code></dt>
325 <dd>Defined when compiling with Clang</dd>
326
327 <dt><code>__clang_major__</code></dt>
328 <dd>Defined to the major version number of Clang (e.g., the 2 in
329 2.0.1).</dd>
330
331 <dt><code>__clang_minor__</code></dt>
332 <dd>Defined to the minor version number of Clang (e.g., the 0 in
333 2.0.1).</dd>
334
335 <dt><code>__clang_patchlevel__</code></dt>
336 <dd>Defined to the patch level of Clang (e.g., the 1 in 2.0.1).</dd>
337
338 <dt><code>__clang_version__</code></dt>
339 <dd>Defined to a string that captures the Clang version, including
340 the Subversion tag or revision number, e.g., "1.5 (trunk
341 102332)".</dd>
342</dl>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]343
344<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]345<h2 id="vectors">Vectors and Extended Vectors</h2>
346<!-- ======================================================================= -->
347
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]348<p>Supports the GCC vector extensions, plus some stuff like V[1].</p>
349
350<p>Also supports <tt>ext_vector</tt>, which additionally support for V.xyzw
351syntax and other tidbits as seen in OpenCL. An example is:</p>
352
353<blockquote>
354<pre>
355typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>;
356typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>;
357
358float4 foo(float2 a, float2 b) {
359 float4 c;
360 c.xz = a;
361 c.yw = b;
362 return c;
363}
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]364</pre>
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]365</blockquote>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]366
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]367<p>Query for this feature with __has_extension(attribute_ext_vector_type).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]368
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]369<p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
370
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]371<!-- ======================================================================= -->
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]372<h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]373<!-- ======================================================================= -->
374
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]375<p>An optional string message can be added to the <tt>deprecated</tt>
376and <tt>unavailable</tt> attributes. For example:</p>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]377
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]378<blockquote>
Chris Lattner4836d6a2010-11-09 19:43:35 +0000[diff] [blame]379<pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]380</blockquote>
381
382<p>If the deprecated or unavailable declaration is used, the message
383will be incorporated into the appropriate diagnostic:</p>
384
385<blockquote>
Chris Lattner4836d6a2010-11-09 19:43:35 +0000[diff] [blame]386<pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! [-Wdeprecated-declarations]
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]387 explode();
388 ^</pre>
389</blockquote>
390
391<p>Query for this feature
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]392with <tt>__has_extension(attribute_deprecated_with_message)</tt>
393and <tt>__has_extension(attribute_unavailable_with_message)</tt>.</p>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]394
395<!-- ======================================================================= -->
396<h2 id="attributes-on-enumerators">Attributes on Enumerators</h2>
397<!-- ======================================================================= -->
398
399<p>Clang allows attributes to be written on individual enumerators.
400This allows enumerators to be deprecated, made unavailable, etc. The
401attribute must appear after the enumerator name and before any
402initializer, like so:</p>
403
404<blockquote>
405<pre>enum OperationMode {
406 OM_Invalid,
407 OM_Normal,
408 OM_Terrified __attribute__((deprecated)),
409 OM_AbortOnError __attribute__((deprecated)) = 4
410};</pre>
411</blockquote>
412
413<p>Attributes on the <tt>enum</tt> declaration do not apply to
414individual enumerators.</p>
415
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]416<p>Query for this feature with <tt>__has_extension(enumerator_attributes)</tt>.</p>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]417
418<!-- ======================================================================= -->
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]419<h2 id="checking_language_features">Checks for Standard Language Features</h2>
420<!-- ======================================================================= -->
421
422<p>The <tt>__has_feature</tt> macro can be used to query if certain standard language features are
423enabled. Those features are listed here.</p>
424
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]425<h3 id="cxx_exceptions">C++ exceptions</h3>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]426
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]427<p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For
Sean Hunt647ba1b2011-06-23 00:42:53 +0000[diff] [blame]428example, compiling code with <tt>-fexceptions</tt> enables C++ exceptions.</p>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]429
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]430<h3 id="cxx_rtti">C++ RTTI</h3>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]431
Ted Kremenek0eb95602009-12-03 02:06:43 +0000[diff] [blame]432<p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example,
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]433compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]434
435<!-- ======================================================================= -->
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]436<h2 id="checking_upcoming_features">Checks for Upcoming Standard Language Features</h2>
437<!-- ======================================================================= -->
438
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]439<p>The <tt>__has_feature</tt> or <tt>__has_extension</tt> macros can be used
440to query if certain upcoming standard language features are enabled. Those
441features are listed here. Features that are not yet implemented will be
442noted.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]443
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]444<h3 id="cxx0x">C++0x</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]445
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]446<p>The features listed below are slated for inclusion in the upcoming
447C++0x standard. As a result, all these features are enabled
448with the <tt>-std=c++0x</tt> option when compiling C++ code.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]449
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]450<h4 id="cxx_access_control_sfinae">C++0x SFINAE includes access control</h4>
Douglas Gregor7822ee32011-05-11 23:45:11 +0000[diff] [blame]451
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]452<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>
Douglas Gregor7822ee32011-05-11 23:45:11 +0000[diff] [blame]453
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]454<h4 id="cxx_alias_templates">C++0x alias templates</h4>
Richard Smith3e4c6c42011-05-05 21:57:07 +0000[diff] [blame]455
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]456<p>Use <tt>__has_feature(cxx_alias_templates)</tt> or
457<tt>__has_extension(cxx_alias_templates)</tt> to determine if support for
Richard Smith3e4c6c42011-05-05 21:57:07 +0000[diff] [blame]458C++0x's alias declarations and alias templates is enabled.</p>
459
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]460<h4 id="cxx_attributes">C++0x attributes</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]461
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]462<p>Use <tt>__has_feature(cxx_attributes)</tt> or
463<tt>__has_extension(cxx_attributes)</tt> to determine if support for attribute
464parsing with C++0x's square bracket notation is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]465
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]466<h4 id="cxx_constexpr">C++0x generalized constant expressions</h4>
467
468<p>Use <tt>__has_feature(cxx_constexpr)</tt> to determine if support
469for generalized constant expressions (e.g., <tt>constexpr</tt>) is
470enabled. Clang does not currently implement this feature.</p>
471
472<h4 id="cxx_decltype">C++0x <tt>decltype()</tt></h4>
473
474<p>Use <tt>__has_feature(cxx_decltype)</tt> or
475<tt>__has_extension(cxx_decltype)</tt> to determine if support for the
476<tt>decltype()</tt> specifier is enabled.</p>
477
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]478<h4 id="cxx_default_function_template_args">C++0x default template arguments in function templates</h4>
Douglas Gregor07508002011-02-05 20:35:30 +0000[diff] [blame]479
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]480<p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or
481<tt>__has_extension(cxx_default_function_template_args)</tt> to determine
482if support for default template arguments in function templates is enabled.</p>
Douglas Gregor07508002011-02-05 20:35:30 +0000[diff] [blame]483
Sean Huntd9624992011-06-23 06:11:37 +0000[diff] [blame]484<h4 id="cxx_delegating_constructors">C++0x delegating constructors</h4>
485
486<p>Use <tt>__has_feature(cxx_delegating_constructors)</tt> to determine if
487support for delegating constructors is enabled.</p>
488
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]489<h4 id="cxx_deleted_functions">C++0x <tt>delete</tt>d functions</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]490
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]491<p>Use <tt>__has_feature(cxx_deleted_functions)</tt> or
492<tt>__has_extension(cxx_deleted_functions)</tt> to determine if support for
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]493deleted function definitions (with <tt>= delete</tt>) is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]494
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]495<h4 id="cxx_explicit_conversions">C++0x explicit conversion functions</h3>
496<p>Use <tt>__has_feature(cxx_explicit_conversions)</tt> to determine if support for <tt>explicit</tt> conversion functions is enabled.</p>
497
Sean Hunte1f6dea2011-08-07 00:34:32 +0000[diff] [blame]498<h4 id="cxx_generalized_initializers">C++0x generalized initializers</h4>
499
500<p>Use <tt>__has_feature(cxx_generalized_initializers)</tt> to determine if
501support for generalized initializers (using braced lists and
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]502<tt>std::initializer_list</tt>) is enabled. Clang does not currently implement
503this feature.</p>
504
505<h4 id="cxx_implicit_moves">C++0x implicit move constructors/assignment operators</h4>
506
507<p>Use <tt>__has_feature(cxx_implicit_moves)</tt> to determine if Clang will implicitly generate move constructors and move assignment operators where needed. Clang does not currently implement this feature.</p>
508
509<h4 id="cxx_inheriting_constructors">C++0x inheriting constructors</h4>
510
511<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>
512
513<h4 id="cxx_inline_namespaces">C++0x inline namespaces</h4>
514
515<p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> or
516<tt>__has_extension(cxx_inline_namespaces)</tt> to determine if support for
517inline namespaces is enabled.</p>
Sean Hunte1f6dea2011-08-07 00:34:32 +0000[diff] [blame]518
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]519<h4 id="cxx_lambdas">C++0x lambdas</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]520
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]521<p>Use <tt>__has_feature(cxx_lambdas)</tt> or
522<tt>__has_extension(cxx_lambdas)</tt> to determine if support for lambdas
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]523is enabled. Clang does not currently implement this feature.</p>
524
525<h4 id="cxx_noexcept">C++0x noexcept</h4>
526
527<p>Use <tt>__has_feature(cxx_noexcept)</tt> or
528<tt>__has_extension(cxx_noexcept)</tt> to determine if support for noexcept
529exception specifications is enabled.</p>
530
531<h4 id="cxx_nonstatic_member_init">C++0x in-class non-static data member initialization</h4>
532
533<p>Use <tt>__has_feature(cxx_nonstatic_member_init)</tt> to determine whether in-class initialization of non-static data members is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]534
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]535<h4 id="cxx_nullptr">C++0x <tt>nullptr</tt></h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]536
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]537<p>Use <tt>__has_feature(cxx_nullptr)</tt> or
538<tt>__has_extension(cxx_nullptr)</tt> to determine if support for
Douglas Gregor84ee2ee2011-05-21 23:15:46 +0000[diff] [blame]539<tt>nullptr</tt> is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]540
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]541<h4 id="cxx_override_control">C++0x <tt>override control</tt></h4>
Anders Carlssonc8b9f792011-03-25 15:04:23 +0000[diff] [blame]542
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]543<p>Use <tt>__has_feature(cxx_override_control)</tt> or
544<tt>__has_extension(cxx_override_control)</tt> to determine if support for
Anders Carlssonc8b9f792011-03-25 15:04:23 +0000[diff] [blame]545the override control keywords is enabled.</p>
546
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]547<h4 id="cxx_reference_qualified_functions">C++0x reference-qualified functions</h4>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]548<p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> or
549<tt>__has_extension(cxx_reference_qualified_functions)</tt> to determine
550if support for reference-qualified functions (e.g., member functions with
551<code>&amp;</code> or <code>&amp;&amp;</code> applied to <code>*this</code>)
552is enabled.</p>
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]553
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]554<h4 id="cxx_range_for">C++0x range-based <tt>for</tt> loop</h4>
Richard Smitha391a462011-04-15 15:14:40 +0000[diff] [blame]555
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]556<p>Use <tt>__has_feature(cxx_range_for)</tt> or
557<tt>__has_extension(cxx_range_for)</tt> to determine if support for the
558range-based for loop is enabled. </p>
Richard Smitha391a462011-04-15 15:14:40 +0000[diff] [blame]559
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]560<h4 id="cxx_raw_string_literals">C++0x raw string literals</h4>
561<p>Use <tt>__has_feature(cxx_raw_string_literals)</tt> to determine if support for raw string literals (e.g., <tt>R"foo\bar"</tt>) is enabled.</p>
562
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]563<h4 id="cxx_rvalue_references">C++0x rvalue references</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]564
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]565<p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or
566<tt>__has_extension(cxx_rvalue_references)</tt> to determine if support for
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]567rvalue references is enabled. </p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]568
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]569<h4 id="cxx_static_assert">C++0x <tt>static_assert()</tt></h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]570
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]571<p>Use <tt>__has_feature(cxx_static_assert)</tt> or
572<tt>__has_extension(cxx_static_assert)</tt> to determine if support for
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]573compile-time assertions using <tt>static_assert</tt> is enabled.</p>
574
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]575<h4 id="cxx_auto_type">C++0x type inference</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]576
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]577<p>Use <tt>__has_feature(cxx_auto_type)</tt> or
578<tt>__has_extension(cxx_auto_type)</tt> to determine C++0x type inference is
579supported using the <tt>auto</tt> specifier. If this is disabled, <tt>auto</tt>
580will instead be a storage class specifier, as in C or C++98.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]581
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]582<h4 id="cxx_strong_enums">C++0x strongly typed enumerations</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]583
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]584<p>Use <tt>__has_feature(cxx_strong_enums)</tt> or
585<tt>__has_extension(cxx_strong_enums)</tt> to determine if support for
586strongly typed, scoped enumerations is enabled.</p>
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]587
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]588<h4 id="cxx_trailing_return">C++0x trailing return type</h4>
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]589
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]590<p>Use <tt>__has_feature(cxx_trailing_return)</tt> or
591<tt>__has_extension(cxx_trailing_return)</tt> to determine if support for the
592alternate function declaration syntax with trailing return type is enabled.</p>
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]593
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]594<h4 id="cxx_unicode_literals">C++0x Unicode string literals</h4>
595<p>Use <tt>__has_feature(cxx_unicode_literals)</tt> to determine if
596support for Unicode string literals is enabled.</p>
Sebastian Redl4561ecd2011-03-15 21:17:12 +0000[diff] [blame]597
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]598<h4 id="cxx_unrestricted_unions">C++0x unrestricted unions</h4>
Sebastian Redl4561ecd2011-03-15 21:17:12 +0000[diff] [blame]599
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]600<p>Use <tt>__has_feature(cxx_unrestricted_unions)</tt> to determine if support for unrestricted unions is enabled. Clang does not currently support this feature.</p>
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]601
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame^]602<h4 id="cxx_user_literals">C++0x user-defined literals</h4>
603
604<p>Use <tt>__has_feature(cxx_user_literals)</tt> to determine if support for user-defined literals is enabled. Clang does not currently support this feature.</p>
605
606<h4 id="cxx_variadic_templates">C++0x variadic templates</h4>
607
608<p>Use <tt>__has_feature(cxx_variadic_templates)</tt> or
609<tt>__has_extension(cxx_variadic_templates)</tt> to determine if support
610for variadic templates is enabled.</p>
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]611
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]612<h3 id="c1x">C1X</h3>
613
614<p>The features listed below are slated for inclusion in the upcoming
615C1X standard. As a result, all these features are enabled
616with the <tt>-std=c1x</tt> option when compiling C code.</p>
617
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]618<h4 id="c_generic_selections">C1X generic selections</h4>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]619
620<p>Use <tt>__has_feature(c_generic_selections)</tt> or
621<tt>__has_extension(c_generic_selections)</tt> to determine if support for
622generic selections is enabled.</p>
623
624<p>As an extension, the C1X generic selection expression is available in all
625languages supported by Clang. The syntax is the same as that given in the
626C1X draft standard.</p>
627
628<p>In C, type compatibility is decided according to the rules given in the
629appropriate standard, but in C++, which lacks the type compatibility rules
630used in C, types are considered compatible only if they are equivalent.</p>
631
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]632<h4 id="c_static_assert">C1X <tt>_Static_assert()</tt></h4>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]633
634<p>Use <tt>__has_feature(c_static_assert)</tt> or
635<tt>__has_extension(c_static_assert)</tt> to determine if support for
636compile-time assertions using <tt>_Static_assert</tt> is enabled.</p>
637
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]638<!-- ======================================================================= -->
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]639<h2 id="checking_type_traits">Checks for Type Traits</h2>
640<!-- ======================================================================= -->
641
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]642<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:
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]643<blockquote>
644<pre>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]645#if __has_extension(is_convertible_to)
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]646template&lt;typename From, typename To&gt;
647struct is_convertible_to {
648 static const bool value = __is_convertible_to(From, To);
649};
650#else
651// Emulate type trait
652#endif
653</pre>
654</blockquote>
655
656<p>The following type traits are supported by Clang:</p>
657<ul>
658 <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li>
659 <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li>
660 <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li>
661 <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li>
662 <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li>
663 <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li>
664 <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li>
665 <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li>
666 <li><code>__is_abstract</code> (GNU, Microsoft)</li>
667 <li><code>__is_base_of</code> (GNU, Microsoft)</li>
668 <li><code>__is_class</code> (GNU, Microsoft)</li>
669 <li><code>__is_convertible_to</code> (Microsoft)</li>
670 <li><code>__is_empty</code> (GNU, Microsoft)</li>
671 <li><code>__is_enum</code> (GNU, Microsoft)</li>
672 <li><code>__is_pod</code> (GNU, Microsoft)</li>
673 <li><code>__is_polymorphic</code> (GNU, Microsoft)</li>
674 <li><code>__is_union</code> (GNU, Microsoft)</li>
675 <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li>
Sean Hunt1fba8282011-07-18 17:22:33 +0000[diff] [blame]676 <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++0x standard library.</li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]677</ul>
678
679<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]680<h2 id="blocks">Blocks</h2>
681<!-- ======================================================================= -->
682
Chris Lattnera7dbdf52009-03-09 07:03:22 +0000[diff] [blame]683<p>The syntax and high level language feature description is in <a
684href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
685details for the clang implementation are in <a
Chris Lattner5d7650b2010-03-16 21:43:03 +0000[diff] [blame]686href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]687
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]688
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]689<p>Query for this feature with __has_extension(blocks).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]690
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]691<!-- ======================================================================= -->
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]692<h2 id="objc_features">Objective-C Features</h2>
693<!-- ======================================================================= -->
694
695<h3 id="objc_instancetype">Related result types</h3>
696
697<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>
698
699<blockquote>
700<pre>
701@interface NSObject
702+ (id)alloc;
703- (id)init;
704@end
705
706@interface NSArray : NSObject
707@end
708</pre>
709</blockquote>
710
711<p>and this common initialization pattern</p>
712
713<blockquote>
714<pre>
715NSArray *array = [[NSArray alloc] init];
716</pre>
717</blockquote>
718
719<p>the type of the expression <code>[NSArray alloc]</code> is
720<code>NSArray*</code> because <code>alloc</code> implicitly has a
721related result type. Similarly, the type of the expression
722<code>[[NSArray alloc] init]</code> is <code>NSArray*</code>, since
723<code>init</code> has a related result type and its receiver is known
724to 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>
725
726<p>To determine whether a method has a related result type, the first
727word in the camel-case selector (e.g., "init" in "initWithObjects") is
728considered, and the method will a related result type if its return
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]729type is compatible with the type of its class and if</p>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]730
731<ul>
732
733 <li>the first word is "alloc" or "new", and the method is a class
734 method, or</li>
735
736 <li>the first word is "autorelease", "init", "retain", or "self",
737 and the method is an instance method.</li>
738
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]739</ul>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]740
741<p>If a method with a related result type is overridden by a subclass
742method, the subclass method must also return a type that is compatible
743with the subclass type. For example:</p>
744
745<blockquote>
746<pre>
747@interface NSString : NSObject
748- (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
749@end
750</pre>
751</blockquote>
752
753<p>Related result types only affect the type of a message send or
754property access via the given method. In all other respects, a method
755with a related result type is treated the same way as method without a
756related result type.</p>
757
758<!-- ======================================================================= -->
John McCallf85e1932011-06-15 23:02:42 +0000[diff] [blame]759<h2 id="objc_arc">Automatic reference counting </h2>
760<!-- ======================================================================= -->
761
762<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>
763
764<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]765<h2 id="overloading-in-c">Function Overloading in C</h2>
766<!-- ======================================================================= -->
767
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]768<p>Clang provides support for C++ function overloading in C. Function
769overloading in C is introduced using the <tt>overloadable</tt> attribute. For
770example, one might provide several overloaded versions of a <tt>tgsin</tt>
771function that invokes the appropriate standard function computing the sine of a
772value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
773precision:</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]774
775<blockquote>
776<pre>
777#include &lt;math.h&gt;
778float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
779double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
780long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
781</pre>
782</blockquote>
783
784<p>Given these declarations, one can call <tt>tgsin</tt> with a
785<tt>float</tt> value to receive a <tt>float</tt> result, with a
786<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
787overloading in C follows the rules of C++ function overloading to pick
788the best overload given the call arguments, with a few C-specific
789semantics:</p>
790<ul>
791 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
792 double</tt> is ranked as a floating-point promotion (per C99) rather
793 than as a floating-point conversion (as in C++).</li>
794
795 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
796 <tt>U*</tt> is considered a pointer conversion (with conversion
797 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
798
799 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
800 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
801 conversion is given "conversion" rank.</li>
802</ul>
803
804<p>The declaration of <tt>overloadable</tt> functions is restricted to
805function declarations and definitions. Most importantly, if any
806function with a given name is given the <tt>overloadable</tt>
807attribute, then all function declarations and definitions with that
808name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]809attribute. This rule even applies to redeclarations of functions whose original
810declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]811
812<blockquote>
813<pre>
814int f(int) __attribute__((overloadable));
815float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
816
817int g(int) __attribute__((overloadable));
818int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
819</pre>
820</blockquote>
821
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]822<p>Functions marked <tt>overloadable</tt> must have
823prototypes. Therefore, the following code is ill-formed:</p>
824
825<blockquote>
826<pre>
827int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
828</pre>
829</blockquote>
830
831<p>However, <tt>overloadable</tt> functions are allowed to use a
832ellipsis 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>
833
834<blockquote>
835<pre>
Chris Lattner02246802009-02-18 22:27:46 +0000[diff] [blame]836void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]837</pre>
838</blockquote>
839
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]840<p>Functions declared with the <tt>overloadable</tt> attribute have
841their names mangled according to the same rules as C++ function
842names. For example, the three <tt>tgsin</tt> functions in our
843motivating example get the mangled names <tt>_Z5tgsinf</tt>,
Chris Lattner71b48d62010-11-28 18:19:13 +0000[diff] [blame]844<tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]845caveats to this use of name mangling:</p>
846
847<ul>
848
849 <li>Future versions of Clang may change the name mangling of
850 functions overloaded in C, so you should not depend on an specific
851 mangling. To be completely safe, we strongly urge the use of
852 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
853
854 <li>The <tt>overloadable</tt> attribute has almost no meaning when
855 used in C++, because names will already be mangled and functions are
856 already overloadable. However, when an <tt>overloadable</tt>
857 function occurs within an <tt>extern "C"</tt> linkage specification,
858 it's name <i>will</i> be mangled in the same way as it would in
859 C.</li>
860</ul>
861
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]862<p>Query for this feature with __has_extension(attribute_overloadable).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]863
864
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]865<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]866<h2 id="builtins">Builtin Functions</h2>
867<!-- ======================================================================= -->
868
869<p>Clang supports a number of builtin library functions with the same syntax as
870GCC, including things like <tt>__builtin_nan</tt>,
871<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
872<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
873addition to the GCC builtins, Clang supports a number of builtins that GCC does
874not, which are listed here.</p>
875
876<p>Please note that Clang does not and will not support all of the GCC builtins
877for vector operations. Instead of using builtins, you should use the functions
878defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
879define portable wrappers for these. Many of the Clang versions of these
880functions are implemented directly in terms of <a href="#vectors">extended
881vector support</a> instead of builtins, in order to reduce the number of
882builtins that we need to implement.</p>
883
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]884<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]885<h3><a name="__builtin_shufflevector">__builtin_shufflevector</a></h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]886<!-- ======================================================================= -->
887
Chris Lattneraad826b2009-09-16 18:56:12 +0000[diff] [blame]888<p><tt>__builtin_shufflevector</tt> is used to express generic vector
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]889permutation/shuffle/swizzle operations. This builtin is also very important for
890the implementation of various target-specific header files like
891<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]892</p>
893
894<p><b>Syntax:</b></p>
895
896<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]897__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]898</pre>
899
900<p><b>Examples:</b></p>
901
902<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]903 // Identity operation - return 4-element vector V1.
904 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
905
906 // "Splat" element 0 of V1 into a 4-element result.
907 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
908
909 // Reverse 4-element vector V1.
910 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
911
912 // Concatenate every other element of 4-element vectors V1 and V2.
913 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
914
915 // Concatenate every other element of 8-element vectors V1 and V2.
916 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]917</pre>
918
919<p><b>Description:</b></p>
920
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]921<p>The first two arguments to __builtin_shufflevector are vectors that have the
922same element type. The remaining arguments are a list of integers that specify
923the elements indices of the first two vectors that should be extracted and
924returned in a new vector. These element indices are numbered sequentially
925starting with the first vector, continuing into the second vector. Thus, if
926vec1 is a 4-element vector, index 5 would refer to the second element of vec2.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]927</p>
928
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]929<p>The result of __builtin_shufflevector is a vector
930with the same element type as vec1/vec2 but that has an element count equal to
931the number of indices specified.
932</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]933
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]934<p>Query for this feature with __has_builtin(__builtin_shufflevector).</p>
935
936<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]937<h3><a name="__builtin_unreachable">__builtin_unreachable</a></h3>
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]938<!-- ======================================================================= -->
939
940<p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in
941the program cannot be reached, even if the compiler might otherwise think it
942can. This is useful to improve optimization and eliminates certain warnings.
943For example, without the <tt>__builtin_unreachable</tt> in the example below,
944the compiler assumes that the inline asm can fall through and prints a "function
945declared 'noreturn' should not return" warning.
946</p>
947
948<p><b>Syntax:</b></p>
949
950<pre>
951__builtin_unreachable()
952</pre>
953
954<p><b>Example of Use:</b></p>
955
956<pre>
957void myabort(void) __attribute__((noreturn));
958void myabort(void) {
959 asm("int3");
960 __builtin_unreachable();
961}
962</pre>
963
964<p><b>Description:</b></p>
965
966<p>The __builtin_unreachable() builtin has completely undefined behavior. Since
967it has undefined behavior, it is a statement that it is never reached and the
968optimizer can take advantage of this to produce better code. This builtin takes
969no arguments and produces a void result.
970</p>
971
972<p>Query for this feature with __has_builtin(__builtin_unreachable).</p>
973
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]974<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]975<h3><a name="__sync_swap">__sync_swap</a></h3>
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]976<!-- ======================================================================= -->
977
978<p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in
979memory.
980</p>
981
982<p><b>Syntax:</b></p>
983
984<pre>
985<i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...)
986</pre>
987
988<p><b>Example of Use:</b></p>
989
990<pre>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]991int old_value = __sync_swap(&amp;value, new_value);
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]992</pre>
993
994<p><b>Description:</b></p>
995
996<p>The __sync_swap() builtin extends the existing __sync_*() family of atomic
997intrinsics to allow code to atomically swap the current value with the new
998value. More importantly, it helps developers write more efficient and correct
999code by avoiding expensive loops around __sync_bool_compare_and_swap() or
1000relying on the platform specific implementation details of
1001__sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier.
1002</p>
1003
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]1004
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]1005<!-- ======================================================================= -->
1006<h2 id="targetspecific">Target-Specific Extensions</h2>
1007<!-- ======================================================================= -->
1008
1009<p>Clang supports some language features conditionally on some targets.</p>
1010
1011<!-- ======================================================================= -->
1012<h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
1013<!-- ======================================================================= -->
1014
1015<p>The X86 backend has these language extensions:</p>
1016
1017<!-- ======================================================================= -->
1018<h4 id="x86-gs-segment">Memory references off the GS segment</h4>
1019<!-- ======================================================================= -->
1020
1021<p>Annotating a pointer with address space #256 causes it to be code generated
Chris Lattnera021e7c2009-05-05 18:54:47 +0000[diff] [blame]1022relative to the X86 GS segment register, and address space #257 causes it to be
1023relative to the X86 FS segment. Note that this is a very very low-level
1024feature that should only be used if you know what you're doing (for example in
1025an OS kernel).</p>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]1026
1027<p>Here is an example:</p>
1028
1029<pre>
1030#define GS_RELATIVE __attribute__((address_space(256)))
1031int foo(int GS_RELATIVE *P) {
1032 return *P;
1033}
1034</pre>
1035
1036<p>Which compiles to (on X86-32):</p>
1037
1038<pre>
1039_foo:
1040 movl 4(%esp), %eax
1041 movl %gs:(%eax), %eax
1042 ret
1043</pre>
1044
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1045<!-- ======================================================================= -->
1046<h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
1047<!-- ======================================================================= -->
1048
1049<p>Clang supports additional attributes that are useful for documenting program
1050invariants and rules for static analysis tools. The extensions documented here
1051are used by the <a
1052href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
1053engine</a> that is part of Clang's Analysis library.</p>
1054
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1055<h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1056
1057<p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
Ted Kremenek4df21142009-04-10 05:04:22 +0000[diff] [blame]1058attribute. This attribute, which is typically affixed to a function prototype,
1059indicates that a call to a given function never returns. Function prototypes for
1060common functions like <tt>exit</tt> are typically annotated with this attribute,
1061as well as a variety of common assertion handlers. Users can educate the static
1062analyzer about their own custom assertion handles (thus cutting down on false
1063positives due to false paths) by marking their own &quot;panic&quot; functions
1064with this attribute.</p>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1065
1066<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
Nick Lewycky625b5862009-06-14 04:08:08 +0000[diff] [blame]1067there are special functions that for all intents and purposes should be
1068considered panic functions (i.e., they are only called when an internal program
1069error occurs) but may actually return so that the program can fail gracefully.
1070The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
1071as being interpreted as &quot;no return&quot; functions by the analyzer (thus
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]1072pruning bogus paths) but will not affect compilation (as in the case of
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1073<tt>noreturn</tt>).</p>
1074
1075<p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]1076same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1077placed at the end of function prototypes:</p>
1078
1079<pre>
1080 void foo() <b>__attribute__((analyzer_noreturn))</b>;
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]1081</pre>
1082
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1083<p>Query for this feature with
1084<tt>__has_attribute(analyzer_noreturn)</tt>.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]1085
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1086<h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3>
1087
1088<p>Many methods in Objective-C have conventional meanings determined
1089by their selectors. For the purposes of static analysis, it is
1090sometimes useful to be able to mark a method as having a particular
1091conventional meaning despite not having the right selector, or as not
1092having the conventional meaning that its selector would suggest.
1093For these use cases, we provide an attribute to specifically describe
1094the <q>method family</q> that a method belongs to.</p>
1095
1096<p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>,
1097where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>,
1098<tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>. This attribute
1099can only be placed at the end of a method declaration:</p>
1100
1101<pre>
1102 - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>;
1103</pre>
1104
1105<p>Users who do not wish to change the conventional meaning of a
1106method, and who merely want to document its non-standard retain and
1107release semantics, should use the
1108<a href="#attr_retain_release">retaining behavior attributes</a>
1109described below.</p>
1110
1111<p>Query for this feature with
1112<tt>__has_attribute(objc_method_family)</tt>.</p>
1113
1114<h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]1115
1116<p>In Objective-C, functions and methods are generally assumed to take
1117and return objects with +0 retain counts, with some exceptions for
1118special methods like <tt>+alloc</tt> and <tt>init</tt>. However,
1119there are exceptions, and so Clang provides attributes to allow these
1120exceptions to be documented, which helps the analyzer find leaks (and
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1121ignore non-leaks). Some exceptions may be better described using
1122the <a href="#attr_method_family"><tt>objc_method_family</tt></a>
1123attribute instead.</p>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]1124
1125<p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>,
1126<tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>,
1127and <tt>cf_returns_not_retained</tt> attributes can be placed on
1128methods and functions that return Objective-C or CoreFoundation
1129objects. They are commonly placed at the end of a function prototype
1130or method declaration:</p>
1131
1132<pre>
1133 id foo() <b>__attribute__((ns_returns_retained))</b>;
1134
1135 - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>;
1136</pre>
1137
1138<p>The <tt>*_returns_retained</tt> attributes specify that the
1139returned object has a +1 retain count.
1140The <tt>*_returns_not_retained</tt> attributes specify that the return
1141object has a +0 retain count, even if the normal convention for its
1142selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the
1143returned object is +0, but is guaranteed to live at least as long as the
1144next flush of an autorelease pool.</p>
1145
1146<p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt>
1147attributes can be placed on an parameter declaration; they specify
1148that the argument is expected to have a +1 retain count, which will be
1149balanced in some way by the function or method.
1150The <tt>ns_consumes_self</tt> attribute can only be placed on an
1151Objective-C method; it specifies that the method expects
1152its <tt>self</tt> parameter to have a +1 retain count, which it will
1153balance in some way.</p>
1154
1155<pre>
1156 void <b>foo(__attribute__((ns_consumed))</b> NSString *string);
1157
1158 - (void) bar <b>__attribute__((ns_consumes_self))</b>;
1159 - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x;
1160</pre>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1161
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1162<p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>,
1163<tt>__has_attribute(ns_returns_retained)</tt>, etc.</p>
1164
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1165
1166<!-- ======================================================================= -->
Caitlin Sadowski73cbbc82011-07-28 18:38:36 +0000[diff] [blame]1167<h2 id="threadsafety">Thread-Safety Annotation Checking</h2>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1168<!-- ======================================================================= -->
1169
1170<p>Clang supports additional attributes for checking basic locking policies in
1171multithreaded programs.
1172Clang currently parses the following list of attributes, although
1173<b>the implementation for these annotations is currently in development.</b>
1174For more details, see the
1175<a href="http://gcc.gnu.org/wiki/ThreadSafetyAnnotation">GCC implementation</a>.
1176</p>
1177
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1178<h4 id="ts_noanal">no_thread_safety_analysis</h4>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1179
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1180<p>Use <tt>__attribute__((no_thread_safety_analysis))</tt> on a function
1181declaration to specify that the thread safety analysis should not be run on that
1182function. This attribute provides an escape hatch (e.g. for situations when it
1183is difficult to annotate the locking policy). </p>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1184
1185<h4 id="ts_lockable">lockable</h4>
1186
1187<p>Use <tt>__attribute__((lockable))</tt> on a class definition to specify
1188that it has a lockable type (e.g. a Mutex class). This annotation is primarily
1189used to check consistency.</p>
1190
1191<h4 id="ts_scopedlockable">scoped_lockable</h4>
1192
1193<p>Use <tt>__attribute__((scoped_lockable))</tt> on a class definition to
1194specify that it has a "scoped" lockable type. Objects of this type will acquire
1195the lock upon construction and release it upon going out of scope.
1196 This annotation is primarily used to check
1197consistency.</p>
1198
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1199<h4 id="ts_guardedvar">guarded_var</h4>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1200
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1201<p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to
1202specify that the variable must be accessed while holding some lock.</p>
1203
1204<h4 id="ts_ptguardedvar">pt_guarded_var</h4>
1205
1206<p>Use <tt>__attribute__((pt_guarded_var))</tt> on a pointer declaration to
1207specify that the pointer must be dereferenced while holding some lock.</p>
1208
1209<h4 id="ts_guardedby">guarded_by(l)</h4>
1210
1211<p>Use <tt>__attribute__((guarded_by(l)))</tt> on a variable declaration to
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1212specify that the variable must be accessed while holding lock <tt>l</tt>.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1213
1214<h4 id="ts_ptguardedby">pt_guarded_by(l)</h4>
1215
1216<p>Use <tt>__attribute__((pt_guarded_by(l)))</tt> on a pointer declaration to
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1217specify that the pointer must be dereferenced while holding lock <tt>l</tt>.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1218
1219<h4 id="ts_acquiredbefore">acquired_before(...)</h4>
1220
1221<p>Use <tt>__attribute__((acquired_before(...)))</tt> on a declaration
1222of a lockable variable to specify that the lock must be acquired before all
1223attribute arguments. Arguments must be lockable type, and there must be at
1224least one argument.</p>
1225
1226<h4 id="ts_acquiredafter">acquired_after(...)</h4>
1227
1228<p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration
1229of a lockable variable to specify that the lock must be acquired after all
1230attribute arguments. Arguments must be lockable type, and there must be at
1231least one argument.</p>
1232
1233<h4 id="ts_elf">exclusive_lock_function(...)</h4>
1234
1235<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
1236declaration to specify that the function acquires all listed locks
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1237exclusively. This attribute takes zero or more arguments: either of lockable
1238type or integers indexing into function parameters of lockable type. If no
1239arguments are given, the acquired lock is implicitly <tt>this</tt> of the
1240enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1241
1242<h4 id="ts_slf">shared_lock_function(...)</h4>
1243
1244<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
1245declaration to specify that the function acquires all listed locks, although
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1246 the locks may be shared (e.g. read locks). This attribute takes zero or more
1247arguments: either of lockable type or integers indexing into function
1248parameters of lockable type. If no arguments are given, the acquired lock is
1249implicitly <tt>this</tt> of the enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1250
1251<h4 id="ts_etf">exclusive_trylock_function(...)</h4>
1252
1253<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
1254declaration to specify that the function will try (without blocking) to acquire
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1255all listed locks exclusively. This attribute takes one or more arguments. The
1256first argument is an integer or boolean value specifying the return value of a
1257successful lock acquisition. The remaining arugments are either of lockable type
1258or integers indexing into function parameters of lockable type. If only one
1259argument is given, the acquired lock is implicitly <tt>this</tt> of the
1260enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1261
1262<h4 id="ts_stf">shared_trylock_function(...)</h4>
1263
1264<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
1265declaration to specify that the function will try (without blocking) to acquire
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1266all listed locks, although the locks may be shared (e.g. read locks). This
1267attribute takes one or more arguments. The first argument is an integer or
1268boolean value specifying the return value of a successful lock acquisition. The
1269remaining arugments are either of lockable type or integers indexing into
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1270function parameters of lockable type. If only one argument is given, the
1271acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
1272
1273<h4 id="ts_uf">unlock_function(...)</h4>
1274
1275<p>Use <tt>__attribute__((unlock_function(...)))</tt> on a function
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1276declaration to specify that the function release all listed locks. This
1277attribute takes zero or more arguments: either of lockable type or integers
1278indexing into function parameters of lockable type. If no arguments are given,
1279the acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1280
1281<h4 id="ts_lr">lock_returned(l)</h4>
1282
1283<p>Use <tt>__attribute__((lock_returned(l)))</tt> on a function
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1284declaration to specify that the function returns lock <tt>l</tt> (<tt>l</tt>
1285must be of lockable type). This annotation is used to aid in resolving lock
1286expressions.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1287
1288<h4 id="ts_le">locks_excluded(...)</h4>
1289
1290<p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1291to specify that the function must not be called with the listed locks. Arguments
1292must be lockable type, and there must be at least one argument.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1293
1294<h4 id="ts_elr">exclusive_locks_required(...)</h4>
1295
1296<p>Use <tt>__attribute__((exclusive_locks_required(...)))</tt> on a function
1297declaration to specify that the function must be called while holding the listed
1298exclusive locks. Arguments must be lockable type, and there must be at
1299least one argument.</p>
1300
1301<h4 id="ts_slr">shared_locks_required(...)</h4>
1302
1303<p>Use <tt>__attribute__((shared_locks_required(...)))</tt> on a function
1304declaration to specify that the function must be called while holding the listed
1305shared locks. Arguments must be lockable type, and there must be at
1306least one argument.</p>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1307
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1308</div>
1309</body>
1310</html>