Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / e97179c675b341927807c718be215c8d1aab8acb / . / docs / LanguageExtensions.html
blob: a7d8019f975d2d424d81fb79d216cfe84a90d84d [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
Douglas Gregore97179c2011-09-08 01:46:34 +0000[diff] [blame^]726<p>A method with a related result type can be declared by using the
727type <tt>instancetype</tt> as its result type. <tt>instancetype</tt>
728is a contextual keyword that is only permitted in the result type of
729an Objective-C method, e.g.</p>
730
731<pre>
732@interface A
733+ (<b>instancetype</b>)constructAnA;
734@end
735</pre>
736
737<p>The related result type can also be inferred for some methods.
738To determine whether a method has an inferred related result type, the first
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]739word in the camel-case selector (e.g., "init" in "initWithObjects") is
740considered, and the method will a related result type if its return
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]741type is compatible with the type of its class and if</p>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]742
743<ul>
744
745 <li>the first word is "alloc" or "new", and the method is a class
746 method, or</li>
747
748 <li>the first word is "autorelease", "init", "retain", or "self",
749 and the method is an instance method.</li>
750
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]751</ul>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]752
753<p>If a method with a related result type is overridden by a subclass
754method, the subclass method must also return a type that is compatible
755with the subclass type. For example:</p>
756
757<blockquote>
758<pre>
759@interface NSString : NSObject
760- (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
761@end
762</pre>
763</blockquote>
764
765<p>Related result types only affect the type of a message send or
766property access via the given method. In all other respects, a method
Douglas Gregore97179c2011-09-08 01:46:34 +0000[diff] [blame^]767with a related result type is treated the same way as method that
768returns <tt>id</tt>.</p>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]769
770<!-- ======================================================================= -->
John McCallf85e1932011-06-15 23:02:42 +0000[diff] [blame]771<h2 id="objc_arc">Automatic reference counting </h2>
772<!-- ======================================================================= -->
773
774<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>
775
776<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]777<h2 id="overloading-in-c">Function Overloading in C</h2>
778<!-- ======================================================================= -->
779
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]780<p>Clang provides support for C++ function overloading in C. Function
781overloading in C is introduced using the <tt>overloadable</tt> attribute. For
782example, one might provide several overloaded versions of a <tt>tgsin</tt>
783function that invokes the appropriate standard function computing the sine of a
784value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
785precision:</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]786
787<blockquote>
788<pre>
789#include &lt;math.h&gt;
790float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
791double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
792long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
793</pre>
794</blockquote>
795
796<p>Given these declarations, one can call <tt>tgsin</tt> with a
797<tt>float</tt> value to receive a <tt>float</tt> result, with a
798<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
799overloading in C follows the rules of C++ function overloading to pick
800the best overload given the call arguments, with a few C-specific
801semantics:</p>
802<ul>
803 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
804 double</tt> is ranked as a floating-point promotion (per C99) rather
805 than as a floating-point conversion (as in C++).</li>
806
807 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
808 <tt>U*</tt> is considered a pointer conversion (with conversion
809 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
810
811 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
812 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
813 conversion is given "conversion" rank.</li>
814</ul>
815
816<p>The declaration of <tt>overloadable</tt> functions is restricted to
817function declarations and definitions. Most importantly, if any
818function with a given name is given the <tt>overloadable</tt>
819attribute, then all function declarations and definitions with that
820name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]821attribute. This rule even applies to redeclarations of functions whose original
822declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]823
824<blockquote>
825<pre>
826int f(int) __attribute__((overloadable));
827float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
828
829int g(int) __attribute__((overloadable));
830int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
831</pre>
832</blockquote>
833
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]834<p>Functions marked <tt>overloadable</tt> must have
835prototypes. Therefore, the following code is ill-formed:</p>
836
837<blockquote>
838<pre>
839int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
840</pre>
841</blockquote>
842
843<p>However, <tt>overloadable</tt> functions are allowed to use a
844ellipsis 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>
845
846<blockquote>
847<pre>
Chris Lattner02246802009-02-18 22:27:46 +0000[diff] [blame]848void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]849</pre>
850</blockquote>
851
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]852<p>Functions declared with the <tt>overloadable</tt> attribute have
853their names mangled according to the same rules as C++ function
854names. For example, the three <tt>tgsin</tt> functions in our
855motivating example get the mangled names <tt>_Z5tgsinf</tt>,
Chris Lattner71b48d62010-11-28 18:19:13 +0000[diff] [blame]856<tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]857caveats to this use of name mangling:</p>
858
859<ul>
860
861 <li>Future versions of Clang may change the name mangling of
862 functions overloaded in C, so you should not depend on an specific
863 mangling. To be completely safe, we strongly urge the use of
864 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
865
866 <li>The <tt>overloadable</tt> attribute has almost no meaning when
867 used in C++, because names will already be mangled and functions are
868 already overloadable. However, when an <tt>overloadable</tt>
869 function occurs within an <tt>extern "C"</tt> linkage specification,
870 it's name <i>will</i> be mangled in the same way as it would in
871 C.</li>
872</ul>
873
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]874<p>Query for this feature with __has_extension(attribute_overloadable).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]875
876
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]877<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]878<h2 id="builtins">Builtin Functions</h2>
879<!-- ======================================================================= -->
880
881<p>Clang supports a number of builtin library functions with the same syntax as
882GCC, including things like <tt>__builtin_nan</tt>,
883<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
884<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
885addition to the GCC builtins, Clang supports a number of builtins that GCC does
886not, which are listed here.</p>
887
888<p>Please note that Clang does not and will not support all of the GCC builtins
889for vector operations. Instead of using builtins, you should use the functions
890defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
891define portable wrappers for these. Many of the Clang versions of these
892functions are implemented directly in terms of <a href="#vectors">extended
893vector support</a> instead of builtins, in order to reduce the number of
894builtins that we need to implement.</p>
895
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]896<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]897<h3><a name="__builtin_shufflevector">__builtin_shufflevector</a></h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]898<!-- ======================================================================= -->
899
Chris Lattneraad826b2009-09-16 18:56:12 +0000[diff] [blame]900<p><tt>__builtin_shufflevector</tt> is used to express generic vector
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]901permutation/shuffle/swizzle operations. This builtin is also very important for
902the implementation of various target-specific header files like
903<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]904</p>
905
906<p><b>Syntax:</b></p>
907
908<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]909__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]910</pre>
911
912<p><b>Examples:</b></p>
913
914<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]915 // Identity operation - return 4-element vector V1.
916 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
917
918 // "Splat" element 0 of V1 into a 4-element result.
919 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
920
921 // Reverse 4-element vector V1.
922 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
923
924 // Concatenate every other element of 4-element vectors V1 and V2.
925 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
926
927 // Concatenate every other element of 8-element vectors V1 and V2.
928 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]929</pre>
930
931<p><b>Description:</b></p>
932
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]933<p>The first two arguments to __builtin_shufflevector are vectors that have the
934same element type. The remaining arguments are a list of integers that specify
935the elements indices of the first two vectors that should be extracted and
936returned in a new vector. These element indices are numbered sequentially
937starting with the first vector, continuing into the second vector. Thus, if
938vec1 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]939</p>
940
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]941<p>The result of __builtin_shufflevector is a vector
942with the same element type as vec1/vec2 but that has an element count equal to
943the number of indices specified.
944</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]945
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]946<p>Query for this feature with __has_builtin(__builtin_shufflevector).</p>
947
948<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]949<h3><a name="__builtin_unreachable">__builtin_unreachable</a></h3>
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]950<!-- ======================================================================= -->
951
952<p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in
953the program cannot be reached, even if the compiler might otherwise think it
954can. This is useful to improve optimization and eliminates certain warnings.
955For example, without the <tt>__builtin_unreachable</tt> in the example below,
956the compiler assumes that the inline asm can fall through and prints a "function
957declared 'noreturn' should not return" warning.
958</p>
959
960<p><b>Syntax:</b></p>
961
962<pre>
963__builtin_unreachable()
964</pre>
965
966<p><b>Example of Use:</b></p>
967
968<pre>
969void myabort(void) __attribute__((noreturn));
970void myabort(void) {
971 asm("int3");
972 __builtin_unreachable();
973}
974</pre>
975
976<p><b>Description:</b></p>
977
978<p>The __builtin_unreachable() builtin has completely undefined behavior. Since
979it has undefined behavior, it is a statement that it is never reached and the
980optimizer can take advantage of this to produce better code. This builtin takes
981no arguments and produces a void result.
982</p>
983
984<p>Query for this feature with __has_builtin(__builtin_unreachable).</p>
985
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]986<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]987<h3><a name="__sync_swap">__sync_swap</a></h3>
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]988<!-- ======================================================================= -->
989
990<p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in
991memory.
992</p>
993
994<p><b>Syntax:</b></p>
995
996<pre>
997<i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...)
998</pre>
999
1000<p><b>Example of Use:</b></p>
1001
1002<pre>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]1003int old_value = __sync_swap(&amp;value, new_value);
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]1004</pre>
1005
1006<p><b>Description:</b></p>
1007
1008<p>The __sync_swap() builtin extends the existing __sync_*() family of atomic
1009intrinsics to allow code to atomically swap the current value with the new
1010value. More importantly, it helps developers write more efficient and correct
1011code by avoiding expensive loops around __sync_bool_compare_and_swap() or
1012relying on the platform specific implementation details of
1013__sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier.
1014</p>
1015
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]1016
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]1017<!-- ======================================================================= -->
1018<h2 id="targetspecific">Target-Specific Extensions</h2>
1019<!-- ======================================================================= -->
1020
1021<p>Clang supports some language features conditionally on some targets.</p>
1022
1023<!-- ======================================================================= -->
1024<h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
1025<!-- ======================================================================= -->
1026
1027<p>The X86 backend has these language extensions:</p>
1028
1029<!-- ======================================================================= -->
1030<h4 id="x86-gs-segment">Memory references off the GS segment</h4>
1031<!-- ======================================================================= -->
1032
1033<p>Annotating a pointer with address space #256 causes it to be code generated
Chris Lattnera021e7c2009-05-05 18:54:47 +0000[diff] [blame]1034relative to the X86 GS segment register, and address space #257 causes it to be
1035relative to the X86 FS segment. Note that this is a very very low-level
1036feature that should only be used if you know what you're doing (for example in
1037an OS kernel).</p>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]1038
1039<p>Here is an example:</p>
1040
1041<pre>
1042#define GS_RELATIVE __attribute__((address_space(256)))
1043int foo(int GS_RELATIVE *P) {
1044 return *P;
1045}
1046</pre>
1047
1048<p>Which compiles to (on X86-32):</p>
1049
1050<pre>
1051_foo:
1052 movl 4(%esp), %eax
1053 movl %gs:(%eax), %eax
1054 ret
1055</pre>
1056
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1057<!-- ======================================================================= -->
1058<h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
1059<!-- ======================================================================= -->
1060
1061<p>Clang supports additional attributes that are useful for documenting program
1062invariants and rules for static analysis tools. The extensions documented here
1063are used by the <a
1064href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
1065engine</a> that is part of Clang's Analysis library.</p>
1066
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1067<h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1068
1069<p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
Ted Kremenek4df21142009-04-10 05:04:22 +0000[diff] [blame]1070attribute. This attribute, which is typically affixed to a function prototype,
1071indicates that a call to a given function never returns. Function prototypes for
1072common functions like <tt>exit</tt> are typically annotated with this attribute,
1073as well as a variety of common assertion handlers. Users can educate the static
1074analyzer about their own custom assertion handles (thus cutting down on false
1075positives due to false paths) by marking their own &quot;panic&quot; functions
1076with this attribute.</p>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1077
1078<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
Nick Lewycky625b5862009-06-14 04:08:08 +0000[diff] [blame]1079there are special functions that for all intents and purposes should be
1080considered panic functions (i.e., they are only called when an internal program
1081error occurs) but may actually return so that the program can fail gracefully.
1082The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
1083as being interpreted as &quot;no return&quot; functions by the analyzer (thus
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]1084pruning bogus paths) but will not affect compilation (as in the case of
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1085<tt>noreturn</tt>).</p>
1086
1087<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]1088same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1089placed at the end of function prototypes:</p>
1090
1091<pre>
1092 void foo() <b>__attribute__((analyzer_noreturn))</b>;
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]1093</pre>
1094
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1095<p>Query for this feature with
1096<tt>__has_attribute(analyzer_noreturn)</tt>.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]1097
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1098<h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3>
1099
1100<p>Many methods in Objective-C have conventional meanings determined
1101by their selectors. For the purposes of static analysis, it is
1102sometimes useful to be able to mark a method as having a particular
1103conventional meaning despite not having the right selector, or as not
1104having the conventional meaning that its selector would suggest.
1105For these use cases, we provide an attribute to specifically describe
1106the <q>method family</q> that a method belongs to.</p>
1107
1108<p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>,
1109where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>,
1110<tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>. This attribute
1111can only be placed at the end of a method declaration:</p>
1112
1113<pre>
1114 - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>;
1115</pre>
1116
1117<p>Users who do not wish to change the conventional meaning of a
1118method, and who merely want to document its non-standard retain and
1119release semantics, should use the
1120<a href="#attr_retain_release">retaining behavior attributes</a>
1121described below.</p>
1122
1123<p>Query for this feature with
1124<tt>__has_attribute(objc_method_family)</tt>.</p>
1125
1126<h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]1127
1128<p>In Objective-C, functions and methods are generally assumed to take
1129and return objects with +0 retain counts, with some exceptions for
1130special methods like <tt>+alloc</tt> and <tt>init</tt>. However,
1131there are exceptions, and so Clang provides attributes to allow these
1132exceptions to be documented, which helps the analyzer find leaks (and
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1133ignore non-leaks). Some exceptions may be better described using
1134the <a href="#attr_method_family"><tt>objc_method_family</tt></a>
1135attribute instead.</p>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]1136
1137<p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>,
1138<tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>,
1139and <tt>cf_returns_not_retained</tt> attributes can be placed on
1140methods and functions that return Objective-C or CoreFoundation
1141objects. They are commonly placed at the end of a function prototype
1142or method declaration:</p>
1143
1144<pre>
1145 id foo() <b>__attribute__((ns_returns_retained))</b>;
1146
1147 - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>;
1148</pre>
1149
1150<p>The <tt>*_returns_retained</tt> attributes specify that the
1151returned object has a +1 retain count.
1152The <tt>*_returns_not_retained</tt> attributes specify that the return
1153object has a +0 retain count, even if the normal convention for its
1154selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the
1155returned object is +0, but is guaranteed to live at least as long as the
1156next flush of an autorelease pool.</p>
1157
1158<p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt>
1159attributes can be placed on an parameter declaration; they specify
1160that the argument is expected to have a +1 retain count, which will be
1161balanced in some way by the function or method.
1162The <tt>ns_consumes_self</tt> attribute can only be placed on an
1163Objective-C method; it specifies that the method expects
1164its <tt>self</tt> parameter to have a +1 retain count, which it will
1165balance in some way.</p>
1166
1167<pre>
1168 void <b>foo(__attribute__((ns_consumed))</b> NSString *string);
1169
1170 - (void) bar <b>__attribute__((ns_consumes_self))</b>;
1171 - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x;
1172</pre>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1173
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1174<p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>,
1175<tt>__has_attribute(ns_returns_retained)</tt>, etc.</p>
1176
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1177
1178<!-- ======================================================================= -->
Caitlin Sadowski73cbbc82011-07-28 18:38:36 +0000[diff] [blame]1179<h2 id="threadsafety">Thread-Safety Annotation Checking</h2>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1180<!-- ======================================================================= -->
1181
1182<p>Clang supports additional attributes for checking basic locking policies in
1183multithreaded programs.
1184Clang currently parses the following list of attributes, although
1185<b>the implementation for these annotations is currently in development.</b>
1186For more details, see the
1187<a href="http://gcc.gnu.org/wiki/ThreadSafetyAnnotation">GCC implementation</a>.
1188</p>
1189
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1190<h4 id="ts_noanal">no_thread_safety_analysis</h4>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1191
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1192<p>Use <tt>__attribute__((no_thread_safety_analysis))</tt> on a function
1193declaration to specify that the thread safety analysis should not be run on that
1194function. This attribute provides an escape hatch (e.g. for situations when it
1195is difficult to annotate the locking policy). </p>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1196
1197<h4 id="ts_lockable">lockable</h4>
1198
1199<p>Use <tt>__attribute__((lockable))</tt> on a class definition to specify
1200that it has a lockable type (e.g. a Mutex class). This annotation is primarily
1201used to check consistency.</p>
1202
1203<h4 id="ts_scopedlockable">scoped_lockable</h4>
1204
1205<p>Use <tt>__attribute__((scoped_lockable))</tt> on a class definition to
1206specify that it has a "scoped" lockable type. Objects of this type will acquire
1207the lock upon construction and release it upon going out of scope.
1208 This annotation is primarily used to check
1209consistency.</p>
1210
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1211<h4 id="ts_guardedvar">guarded_var</h4>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1212
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1213<p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to
1214specify that the variable must be accessed while holding some lock.</p>
1215
1216<h4 id="ts_ptguardedvar">pt_guarded_var</h4>
1217
1218<p>Use <tt>__attribute__((pt_guarded_var))</tt> on a pointer declaration to
1219specify that the pointer must be dereferenced while holding some lock.</p>
1220
1221<h4 id="ts_guardedby">guarded_by(l)</h4>
1222
1223<p>Use <tt>__attribute__((guarded_by(l)))</tt> on a variable declaration to
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1224specify that the variable must be accessed while holding lock <tt>l</tt>.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1225
1226<h4 id="ts_ptguardedby">pt_guarded_by(l)</h4>
1227
1228<p>Use <tt>__attribute__((pt_guarded_by(l)))</tt> on a pointer declaration to
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1229specify that the pointer must be dereferenced while holding lock <tt>l</tt>.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1230
1231<h4 id="ts_acquiredbefore">acquired_before(...)</h4>
1232
1233<p>Use <tt>__attribute__((acquired_before(...)))</tt> on a declaration
1234of a lockable variable to specify that the lock must be acquired before all
1235attribute arguments. Arguments must be lockable type, and there must be at
1236least one argument.</p>
1237
1238<h4 id="ts_acquiredafter">acquired_after(...)</h4>
1239
1240<p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration
1241of a lockable variable to specify that the lock must be acquired after all
1242attribute arguments. Arguments must be lockable type, and there must be at
1243least one argument.</p>
1244
1245<h4 id="ts_elf">exclusive_lock_function(...)</h4>
1246
1247<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
1248declaration to specify that the function acquires all listed locks
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1249exclusively. This attribute takes zero or more arguments: either of lockable
1250type or integers indexing into function parameters of lockable type. If no
1251arguments are given, the acquired lock is implicitly <tt>this</tt> of the
1252enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1253
1254<h4 id="ts_slf">shared_lock_function(...)</h4>
1255
1256<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
1257declaration to specify that the function acquires all listed locks, although
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1258 the locks may be shared (e.g. read locks). This attribute takes zero or more
1259arguments: either of lockable type or integers indexing into function
1260parameters of lockable type. If no arguments are given, the acquired lock is
1261implicitly <tt>this</tt> of the enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1262
1263<h4 id="ts_etf">exclusive_trylock_function(...)</h4>
1264
1265<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
1266declaration to specify that the function will try (without blocking) to acquire
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1267all listed locks exclusively. This attribute takes one or more arguments. The
1268first argument is an integer or boolean value specifying the return value of a
1269successful lock acquisition. The remaining arugments are either of lockable type
1270or integers indexing into function parameters of lockable type. If only one
1271argument is given, the acquired lock is implicitly <tt>this</tt> of the
1272enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1273
1274<h4 id="ts_stf">shared_trylock_function(...)</h4>
1275
1276<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
1277declaration to specify that the function will try (without blocking) to acquire
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1278all listed locks, although the locks may be shared (e.g. read locks). This
1279attribute takes one or more arguments. The first argument is an integer or
1280boolean value specifying the return value of a successful lock acquisition. The
1281remaining arugments are either of lockable type or integers indexing into
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1282function parameters of lockable type. If only one argument is given, the
1283acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
1284
1285<h4 id="ts_uf">unlock_function(...)</h4>
1286
1287<p>Use <tt>__attribute__((unlock_function(...)))</tt> on a function
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1288declaration to specify that the function release all listed locks. This
1289attribute takes zero or more arguments: either of lockable type or integers
1290indexing into function parameters of lockable type. If no arguments are given,
1291the acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1292
1293<h4 id="ts_lr">lock_returned(l)</h4>
1294
1295<p>Use <tt>__attribute__((lock_returned(l)))</tt> on a function
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1296declaration to specify that the function returns lock <tt>l</tt> (<tt>l</tt>
1297must be of lockable type). This annotation is used to aid in resolving lock
1298expressions.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1299
1300<h4 id="ts_le">locks_excluded(...)</h4>
1301
1302<p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1303to specify that the function must not be called with the listed locks. Arguments
1304must be lockable type, and there must be at least one argument.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1305
1306<h4 id="ts_elr">exclusive_locks_required(...)</h4>
1307
1308<p>Use <tt>__attribute__((exclusive_locks_required(...)))</tt> on a function
1309declaration to specify that the function must be called while holding the listed
1310exclusive locks. Arguments must be lockable type, and there must be at
1311least one argument.</p>
1312
1313<h4 id="ts_slr">shared_locks_required(...)</h4>
1314
1315<p>Use <tt>__attribute__((shared_locks_required(...)))</tt> on a function
1316declaration to specify that the function must be called while holding the listed
1317shared locks. Arguments must be lockable type, and there must be at
1318least one argument.</p>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1319
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1320</div>
1321</body>
1322</html>