Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / 3e4c6c4c79a03f5cb0c4671d7c282d623c6dc35e / . / docs / LanguageExtensions.html
blob: 9dcddfad60382f0e0a834f60a0753832b2d89916 [file] [log] [blame]
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1<html>
2<head>
3<title>Clang Language Extensions</title>
4<link type="text/css" rel="stylesheet" href="../menu.css" />
5<link type="text/css" rel="stylesheet" href="../content.css" />
6<style type="text/css">
7td {
8 vertical-align: top;
9}
10</style>
11</head>
12<body>
13
14<!--#include virtual="../menu.html.incl"-->
15
16<div id="content">
17
18<h1>Clang Language Extensions</h1>
19
20<ul>
21<li><a href="#intro">Introduction</a></li>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]22<li><a href="#feature_check">Feature Checking Macros</a></li>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]23<li><a href="#has_include">Include File Checking Macros</a></li>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]24<li><a href="#builtinmacros">Builtin Macros</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]25<li><a href="#vectors">Vectors and Extended Vectors</a></li>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]26<li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li>
27<li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]28<li><a href="#checking_language_features">Checks for Standard Language Features</a></li>
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]29 <ul>
30 <li><a href="#cxx_exceptions">C++ exceptions</a></li>
31 <li><a href="#cxx_rtti">C++ RTTI</a></li>
32 </ul>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]33<li><a href="#checking_upcoming_features">Checks for Upcoming Standard Language Features</a></li>
34 <ul>
Richard Smith3e4c6c42011-05-05 21:57:07 +0000[diff] [blame^]35 <li><a href="#cxx_alias_templates">C++0x alias templates</a></li>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]36 <li><a href="#cxx_attributes">C++0x attributes</a></li>
37 <li><a href="#cxx_decltype">C++0x <tt>decltype()</tt></a></li>
Douglas Gregor07508002011-02-05 20:35:30 +0000[diff] [blame]38 <li><a href="#cxx_default_function_template_args">C++0x default template arguments in function templates</a></li>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]39 <li><a href="#cxx_deleted_functions">C++0x deleted functions</a></li>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]40 <li><a href="#cxx_lambdas">C++0x lambdas</a></li>
41 <li><a href="#cxx_nullptr">C++0x nullptr</a></li>
Anders Carlssonc8b9f792011-03-25 15:04:23 +0000[diff] [blame]42 <li><a href="#cxx_override_control">C++0x override control</a></li>
Richard Smitha391a462011-04-15 15:14:40 +0000[diff] [blame]43 <li><a href="#cxx_range_for">C++0x range-based for loop</a></li>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]44 <li><a href="#cxx_rvalue_references">C++0x rvalue references</a></li>
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]45 <li><a href="#cxx_reference_qualified_functions">C++0x reference-qualified functions</a></li>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]46 <li><a href="#cxx_static_assert">C++0x <tt>static_assert()</tt></a></li>
47 <li><a href="#cxx_auto_type">C++0x type inference</a></li>
48 <li><a href="#cxx_variadic_templates">C++0x variadic templates</a></li>
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]49 <li><a href="#cxx_inline_namespaces">C++0x inline namespaces</a></li>
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]50 <li><a href="#cxx_strong_enums">C++0x strongly-typed enumerations</a></li>
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]51 <li><a href="#cxx_trailing_return">C++0x trailing return type</a></li>
Sebastian Redl4561ecd2011-03-15 21:17:12 +0000[diff] [blame]52 <li><a href="#cxx_noexcept">C++0x noexcept specification</a></li>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]53 </ul>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]54<li><a href="#checking_type_traits">Checks for Type Traits</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]55<li><a href="#blocks">Blocks</a></li>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]56<li><a href="#overloading-in-c">Function Overloading in C</a></li>
Peter Collingbournef111d932011-04-15 00:35:48 +0000[diff] [blame]57<li><a href="#generic-selections">Generic Selections</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]58<li><a href="#builtins">Builtin Functions</a>
59 <ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]60 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]61 <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li>
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]62 <li><a href="#__sync_swap">__sync_swap</a></li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]63 </ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]64</li>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]65<li><a href="#targetspecific">Target-Specific Extensions</a>
66 <ul>
67 <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li>
68 </ul>
69</li>
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]70<li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]71</ul>
72
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]73<!-- ======================================================================= -->
74<h2 id="intro">Introduction</h2>
75<!-- ======================================================================= -->
76
77<p>This document describes the language extensions provided by Clang. In
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]78addition to the language extensions listed here, Clang aims to support a broad
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]79range of GCC extensions. Please see the <a
80href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
81more information on these extensions.</p>
82
83<!-- ======================================================================= -->
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]84<h2 id="feature_check">Feature Checking Macros</h2>
85<!-- ======================================================================= -->
86
87<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]88on them. In order to allow fine-grain features checks, we support three builtin
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]89function-like macros. This allows you to directly test for a feature in your
90code without having to resort to something like autoconf or fragile "compiler
91version checks".</p>
92
93<!-- ======================================================================= -->
94<h3 id="__has_builtin">__has_builtin</h3>
95<!-- ======================================================================= -->
96
97<p>This function-like macro takes a single identifier argument that is the name
98of a builtin function. It evaluates to 1 if the builtin is supported or 0 if
99not. It can be used like this:</p>
100
101<blockquote>
102<pre>
103#ifndef __has_builtin // Optional of course.
104 #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
105#endif
106
107...
108#if __has_builtin(__builtin_trap)
109 __builtin_trap();
110#else
111 abort();
112#endif
113...
114</pre>
115</blockquote>
116
117
118<!-- ======================================================================= -->
119<h3 id="__has_feature">__has_feature</h3>
120<!-- ======================================================================= -->
121
122<p>This function-like macro takes a single identifier argument that is the name
123of a feature. It evaluates to 1 if the feature is supported or 0 if not. It
124can be used like this:</p>
125
126<blockquote>
127<pre>
128#ifndef __has_feature // Optional of course.
129 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
130#endif
131
132...
133#if __has_feature(attribute_overloadable) || \
134 __has_feature(blocks)
135...
136#endif
137...
138</pre>
139</blockquote>
140
141<p>The feature tag is described along with the language feature below.</p>
142
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]143<!-- ======================================================================= -->
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]144<h3 id="__has_attribute">__has_attribute</h3>
145<!-- ======================================================================= -->
146
147<p>This function-like macro takes a single identifier argument that is the name
148of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It
149can be used like this:</p>
150
151<blockquote>
152<pre>
153#ifndef __has_attribute // Optional of course.
154 #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
155#endif
156
157...
Anders Carlsson961003d2011-01-24 03:54:51 +0000[diff] [blame]158#if __has_attribute(always_inline)
159#define ALWAYS_INLINE __attribute__((always_inline))
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]160#else
Anders Carlsson961003d2011-01-24 03:54:51 +0000[diff] [blame]161#define ALWAYS_INLINE
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]162#endif
163...
164</pre>
165</blockquote>
166
167<!-- ======================================================================= -->
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]168<h2 id="has_include">Include File Checking Macros</h2>
169<!-- ======================================================================= -->
170
171<p>Not all developments systems have the same include files.
172The <a href="#__has_include">__has_include</a> and
173<a href="#__has_include_next">__has_include_next</a> macros allow you to
174check for the existence of an include file before doing
175a possibly failing #include directive.</p>
176
177<!-- ======================================================================= -->
178<h3 id="__has_include">__has_include</h3>
179<!-- ======================================================================= -->
180
181<p>This function-like macro takes a single file name string argument that
182is the name of an include file. It evaluates to 1 if the file can
183be found using the include paths, or 0 otherwise:</p>
184
185<blockquote>
186<pre>
187// Note the two possible file name string formats.
188#if __has_include("myinclude.h") && __has_include(&lt;stdint.h&gt;)
189# include "myinclude.h"
190#endif
191
192// To avoid problem with non-clang compilers not having this macro.
193#if defined(__has_include) && __has_include("myinclude.h")
194# include "myinclude.h"
195#endif
196</pre>
197</blockquote>
198
199<p>To test for this feature, use #if defined(__has_include).</p>
200
201<!-- ======================================================================= -->
202<h3 id="__has_include_next">__has_include_next</h3>
203<!-- ======================================================================= -->
204
205<p>This function-like macro takes a single file name string argument that
206is the name of an include file. It is like __has_include except that it
207looks for the second instance of the given file found in the include
208paths. It evaluates to 1 if the second instance of the file can
209be found using the include paths, or 0 otherwise:</p>
210
211<blockquote>
212<pre>
213// Note the two possible file name string formats.
214#if __has_include_next("myinclude.h") && __has_include_next(&lt;stdint.h&gt;)
215# include_next "myinclude.h"
216#endif
217
218// To avoid problem with non-clang compilers not having this macro.
219#if defined(__has_include_next) && __has_include_next("myinclude.h")
220# include_next "myinclude.h"
221#endif
222</pre>
223</blockquote>
224
225<p>Note that __has_include_next, like the GNU extension
226#include_next directive, is intended for use in headers only,
227and will issue a warning if used in the top-level compilation
228file. A warning will also be issued if an absolute path
229is used in the file argument.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]230
231<!-- ======================================================================= -->
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]232<h2 id="builtinmacros">Builtin Macros</h2>
233<!-- ======================================================================= -->
234
Douglas Gregor4290fbd2010-04-30 02:51:06 +0000[diff] [blame]235<dl>
236 <dt><code>__BASE_FILE__</code></dt>
237 <dd>Defined to a string that contains the name of the main input
238 file passed to Clang.</dd>
239
240 <dt><code>__COUNTER__</code></dt>
241 <dd>Defined to an integer value that starts at zero and is
242 incremented each time the <code>__COUNTER__</code> macro is
243 expanded.</dd>
244
245 <dt><code>__INCLUDE_LEVEL__</code></dt>
246 <dd>Defined to an integral value that is the include depth of the
247 file currently being translated. For the main file, this value is
248 zero.</dd>
249
250 <dt><code>__TIMESTAMP__</code></dt>
251 <dd>Defined to the date and time of the last modification of the
252 current source file.</dd>
253
254 <dt><code>__clang__</code></dt>
255 <dd>Defined when compiling with Clang</dd>
256
257 <dt><code>__clang_major__</code></dt>
258 <dd>Defined to the major version number of Clang (e.g., the 2 in
259 2.0.1).</dd>
260
261 <dt><code>__clang_minor__</code></dt>
262 <dd>Defined to the minor version number of Clang (e.g., the 0 in
263 2.0.1).</dd>
264
265 <dt><code>__clang_patchlevel__</code></dt>
266 <dd>Defined to the patch level of Clang (e.g., the 1 in 2.0.1).</dd>
267
268 <dt><code>__clang_version__</code></dt>
269 <dd>Defined to a string that captures the Clang version, including
270 the Subversion tag or revision number, e.g., "1.5 (trunk
271 102332)".</dd>
272</dl>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]273
274<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]275<h2 id="vectors">Vectors and Extended Vectors</h2>
276<!-- ======================================================================= -->
277
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]278<p>Supports the GCC vector extensions, plus some stuff like V[1].</p>
279
280<p>Also supports <tt>ext_vector</tt>, which additionally support for V.xyzw
281syntax and other tidbits as seen in OpenCL. An example is:</p>
282
283<blockquote>
284<pre>
285typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>;
286typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>;
287
288float4 foo(float2 a, float2 b) {
289 float4 c;
290 c.xz = a;
291 c.yw = b;
292 return c;
293}
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]294</pre>
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]295</blockquote>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]296
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]297<p>Query for this feature with __has_feature(attribute_ext_vector_type).</p>
298
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]299<p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
300
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]301<!-- ======================================================================= -->
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]302<h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]303<!-- ======================================================================= -->
304
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]305<p>An optional string message can be added to the <tt>deprecated</tt>
306and <tt>unavailable</tt> attributes. For example:</p>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]307
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]308<blockquote>
Chris Lattner4836d6a2010-11-09 19:43:35 +0000[diff] [blame]309<pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]310</blockquote>
311
312<p>If the deprecated or unavailable declaration is used, the message
313will be incorporated into the appropriate diagnostic:</p>
314
315<blockquote>
Chris Lattner4836d6a2010-11-09 19:43:35 +0000[diff] [blame]316<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]317 explode();
318 ^</pre>
319</blockquote>
320
321<p>Query for this feature
322with <tt>__has_feature(attribute_deprecated_with_message)</tt>
323and <tt>__has_feature(attribute_unavailable_with_message)</tt>.</p>
324
325<!-- ======================================================================= -->
326<h2 id="attributes-on-enumerators">Attributes on Enumerators</h2>
327<!-- ======================================================================= -->
328
329<p>Clang allows attributes to be written on individual enumerators.
330This allows enumerators to be deprecated, made unavailable, etc. The
331attribute must appear after the enumerator name and before any
332initializer, like so:</p>
333
334<blockquote>
335<pre>enum OperationMode {
336 OM_Invalid,
337 OM_Normal,
338 OM_Terrified __attribute__((deprecated)),
339 OM_AbortOnError __attribute__((deprecated)) = 4
340};</pre>
341</blockquote>
342
343<p>Attributes on the <tt>enum</tt> declaration do not apply to
344individual enumerators.</p>
345
346<p>Query for this feature with <tt>__has_feature(enumerator_attributes)</tt>.</p>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]347
348<!-- ======================================================================= -->
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]349<h2 id="checking_language_features">Checks for Standard Language Features</h2>
350<!-- ======================================================================= -->
351
352<p>The <tt>__has_feature</tt> macro can be used to query if certain standard language features are
353enabled. Those features are listed here.</p>
354
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]355<h3 id="cxx_exceptions">C++ exceptions</h3>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]356
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]357<p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For
358example, compiling code with <tt>-fexceptions</tt> enables C++ exceptions.</p>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]359
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]360<h3 id="cxx_rtti">C++ RTTI</h3>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]361
Ted Kremenek0eb95602009-12-03 02:06:43 +0000[diff] [blame]362<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]363compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]364
365<!-- ======================================================================= -->
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]366<h2 id="checking_upcoming_features">Checks for Upcoming Standard Language Features</h2>
367<!-- ======================================================================= -->
368
369<p>The <tt>__has_feature</tt> macro can be used to query if certain upcoming
370standard language features are enabled. Those features are listed here.</p>
371
372<p>Currently, all features listed here are slated for inclusion in the upcoming
373C++0x standard. As a result, all the features that clang supports are enabled
374with the <tt>-std=c++0x</tt> option when compiling C++ code. Features that are
375not yet implemented will be noted.</p>
376
377<h3 id="cxx_decltype">C++0x <tt>decltype()</tt></h3>
378
379<p>Use <tt>__has_feature(cxx_decltype)</tt> to determine if support for the
380<tt>decltype()</tt> specifier is enabled.</p>
381
Richard Smith3e4c6c42011-05-05 21:57:07 +0000[diff] [blame^]382<h3 id="cxx_alias_templates">C++0x alias templates</h3>
383
384<p>Use <tt>__has_feature(cxx_alias_templates)</tt> to determine if support for
385C++0x's alias declarations and alias templates is enabled.</p>
386
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]387<h3 id="cxx_attributes">C++0x attributes</h3>
388
389<p>Use <tt>__has_feature(cxx_attributes)</tt> to determine if support for
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]390attribute parsing with C++0x's square bracket notation is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]391
Douglas Gregor07508002011-02-05 20:35:30 +0000[diff] [blame]392<h3 id="cxx_default_function_template_args">C++0x default template arguments in function templates</h3>
393
394<p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> to determine if support for default template arguments in function templates is enabled.</p>
395
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]396<h3 id="cxx_deleted_functions">C++0x deleted functions</tt></h3>
397
398<p>Use <tt>__has_feature(cxx_deleted_functions)</tt> to determine if support for
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]399deleted function definitions (with <tt>= delete</tt>) is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]400
Douglas Gregor9cc90a32010-01-13 16:27:49 +0000[diff] [blame]401<h3 id="cxx_lambdas">C++0x lambdas</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]402
403<p>Use <tt>__has_feature(cxx_lambdas)</tt> to determine if support for
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]404lambdas is enabled. clang does not currently implement this feature.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]405
406<h3 id="cxx_nullptr">C++0x <tt>nullptr</tt></h3>
407
408<p>Use <tt>__has_feature(cxx_nullptr)</tt> to determine if support for
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]409<tt>nullptr</tt> is enabled. clang does not yet fully implement this
410feature.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]411
Anders Carlssonc8b9f792011-03-25 15:04:23 +0000[diff] [blame]412<h3 id="cxx_override_control">C++0x <tt>override control</tt></h3>
413
414<p>Use <tt>__has_feature(cxx_override_control)</tt> to determine if support for
415the override control keywords is enabled.</p>
416
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]417<h3 id="cxx_reference_qualified_functions">C++0x reference-qualified functions</h3>
418<p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> to determine if support for reference-qualified functions (e.g., member functions with <code>&amp;</code> or <code>&amp;&amp;</code> applied to <code>*this</code>) is enabled.</p>
419
Richard Smitha391a462011-04-15 15:14:40 +0000[diff] [blame]420<h3 id="cxx_range_for">C++0x range-based for loop</tt></h3>
421
422<p>Use <tt>__has_feature(cxx_range_for)</tt> to determine if support for
423the range-based for loop is enabled. </p>
424
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]425<h3 id="cxx_rvalue_references">C++0x rvalue references</tt></h3>
426
427<p>Use <tt>__has_feature(cxx_rvalue_references)</tt> to determine if support for
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]428rvalue references is enabled. </p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]429
430<h3 id="cxx_static_assert">C++0x <tt>static_assert()</tt></h3>
431
432<p>Use <tt>__has_feature(cxx_static_assert)</tt> to determine if support for
433compile-time assertions using <tt>static_assert</tt> is enabled.</p>
434
435<h3 id="cxx_auto_type">C++0x type inference</h3>
436
437<p>Use <tt>__has_feature(cxx_auto_type)</tt> to determine C++0x type inference
438is supported using the <tt>auto</tt> specifier. If this is disabled,
Richard Smithfd405ef2011-02-23 00:41:16 +0000[diff] [blame]439<tt>auto</tt> will instead be a storage class specifier, as in C or C++98.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]440
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]441<h3 id="cxx_variadic_templates">C++0x variadic templates</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]442
443<p>Use <tt>__has_feature(cxx_variadic_templates)</tt> to determine if support
Douglas Gregor83d77812011-01-19 23:15:20 +0000[diff] [blame]444for variadic templates is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]445
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]446<h3 id="cxx_inline_namespaces">C++0x inline namespaces</h3>
447
448<p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> to determine if support for
449inline namespaces is enabled.</p>
450
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]451<h3 id="cxx_trailing_return">C++0x trailing return type</h3>
452
453<p>Use <tt>__has_feature(cxx_trailing_return)</tt> to determine if support for
454the alternate function declaration syntax with trailing return type is enabled.</p>
455
Sebastian Redl4561ecd2011-03-15 21:17:12 +0000[diff] [blame]456<h3 id="cxx_noexcept">C++0x noexcept</h3>
457
458<p>Use <tt>__has_feature(cxx_noexcept)</tt> to determine if support for
459noexcept exception specifications is enabled.</p>
460
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]461<h3 id="cxx_strong_enums">C++0x strongly typed enumerations</h3>
462
463<p>Use <tt>__has_feature(cxx_strong_enums)</tt> to determine if support for
464strongly typed, scoped enumerations is enabled.</p>
465
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]466<!-- ======================================================================= -->
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]467<h2 id="checking_type_traits">Checks for Type Traits</h2>
468<!-- ======================================================================= -->
469
470<p>Clang supports the <a hef="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_feature(X)</code> indicates the presence of the type trait. For example:
471<blockquote>
472<pre>
473#if __has_feature(is_convertible_to)
474template&lt;typename From, typename To&gt;
475struct is_convertible_to {
476 static const bool value = __is_convertible_to(From, To);
477};
478#else
479// Emulate type trait
480#endif
481</pre>
482</blockquote>
483
484<p>The following type traits are supported by Clang:</p>
485<ul>
486 <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li>
487 <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li>
488 <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li>
489 <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li>
490 <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li>
491 <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li>
492 <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li>
493 <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li>
494 <li><code>__is_abstract</code> (GNU, Microsoft)</li>
495 <li><code>__is_base_of</code> (GNU, Microsoft)</li>
496 <li><code>__is_class</code> (GNU, Microsoft)</li>
497 <li><code>__is_convertible_to</code> (Microsoft)</li>
498 <li><code>__is_empty</code> (GNU, Microsoft)</li>
499 <li><code>__is_enum</code> (GNU, Microsoft)</li>
500 <li><code>__is_pod</code> (GNU, Microsoft)</li>
501 <li><code>__is_polymorphic</code> (GNU, Microsoft)</li>
502 <li><code>__is_union</code> (GNU, Microsoft)</li>
503 <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li>
504</ul>
505
506<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]507<h2 id="blocks">Blocks</h2>
508<!-- ======================================================================= -->
509
Chris Lattnera7dbdf52009-03-09 07:03:22 +0000[diff] [blame]510<p>The syntax and high level language feature description is in <a
511href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
512details for the clang implementation are in <a
Chris Lattner5d7650b2010-03-16 21:43:03 +0000[diff] [blame]513href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]514
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]515
516<p>Query for this feature with __has_feature(blocks).</p>
517
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]518<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]519<h2 id="overloading-in-c">Function Overloading in C</h2>
520<!-- ======================================================================= -->
521
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]522<p>Clang provides support for C++ function overloading in C. Function
523overloading in C is introduced using the <tt>overloadable</tt> attribute. For
524example, one might provide several overloaded versions of a <tt>tgsin</tt>
525function that invokes the appropriate standard function computing the sine of a
526value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
527precision:</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]528
529<blockquote>
530<pre>
531#include &lt;math.h&gt;
532float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
533double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
534long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
535</pre>
536</blockquote>
537
538<p>Given these declarations, one can call <tt>tgsin</tt> with a
539<tt>float</tt> value to receive a <tt>float</tt> result, with a
540<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
541overloading in C follows the rules of C++ function overloading to pick
542the best overload given the call arguments, with a few C-specific
543semantics:</p>
544<ul>
545 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
546 double</tt> is ranked as a floating-point promotion (per C99) rather
547 than as a floating-point conversion (as in C++).</li>
548
549 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
550 <tt>U*</tt> is considered a pointer conversion (with conversion
551 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
552
553 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
554 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
555 conversion is given "conversion" rank.</li>
556</ul>
557
558<p>The declaration of <tt>overloadable</tt> functions is restricted to
559function declarations and definitions. Most importantly, if any
560function with a given name is given the <tt>overloadable</tt>
561attribute, then all function declarations and definitions with that
562name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]563attribute. This rule even applies to redeclarations of functions whose original
564declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]565
566<blockquote>
567<pre>
568int f(int) __attribute__((overloadable));
569float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
570
571int g(int) __attribute__((overloadable));
572int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
573</pre>
574</blockquote>
575
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]576<p>Functions marked <tt>overloadable</tt> must have
577prototypes. Therefore, the following code is ill-formed:</p>
578
579<blockquote>
580<pre>
581int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
582</pre>
583</blockquote>
584
585<p>However, <tt>overloadable</tt> functions are allowed to use a
586ellipsis 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>
587
588<blockquote>
589<pre>
Chris Lattner02246802009-02-18 22:27:46 +0000[diff] [blame]590void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]591</pre>
592</blockquote>
593
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]594<p>Functions declared with the <tt>overloadable</tt> attribute have
595their names mangled according to the same rules as C++ function
596names. For example, the three <tt>tgsin</tt> functions in our
597motivating example get the mangled names <tt>_Z5tgsinf</tt>,
Chris Lattner71b48d62010-11-28 18:19:13 +0000[diff] [blame]598<tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]599caveats to this use of name mangling:</p>
600
601<ul>
602
603 <li>Future versions of Clang may change the name mangling of
604 functions overloaded in C, so you should not depend on an specific
605 mangling. To be completely safe, we strongly urge the use of
606 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
607
608 <li>The <tt>overloadable</tt> attribute has almost no meaning when
609 used in C++, because names will already be mangled and functions are
610 already overloadable. However, when an <tt>overloadable</tt>
611 function occurs within an <tt>extern "C"</tt> linkage specification,
612 it's name <i>will</i> be mangled in the same way as it would in
613 C.</li>
614</ul>
615
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]616<p>Query for this feature with __has_feature(attribute_overloadable).</p>
617
618
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]619<!-- ======================================================================= -->
Peter Collingbournef111d932011-04-15 00:35:48 +0000[diff] [blame]620<h2 id="generic-selections">Generic Selections</h2>
621<!-- ======================================================================= -->
622
623<p>The C1X generic selection expression is available in all languages
624supported by Clang. The syntax is the same as that given in the C1X draft
625standard.</p>
626
627<p>In C, type compatibility is decided according to the rules given in the
628appropriate standard, but in C++, which lacks the type compatibility rules
629used in C, types are considered compatible only if they are equivalent.</p>
630
631<p>Query for this feature with __has_feature(generic_selections).</p>
632
633<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]634<h2 id="builtins">Builtin Functions</h2>
635<!-- ======================================================================= -->
636
637<p>Clang supports a number of builtin library functions with the same syntax as
638GCC, including things like <tt>__builtin_nan</tt>,
639<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
640<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
641addition to the GCC builtins, Clang supports a number of builtins that GCC does
642not, which are listed here.</p>
643
644<p>Please note that Clang does not and will not support all of the GCC builtins
645for vector operations. Instead of using builtins, you should use the functions
646defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
647define portable wrappers for these. Many of the Clang versions of these
648functions are implemented directly in terms of <a href="#vectors">extended
649vector support</a> instead of builtins, in order to reduce the number of
650builtins that we need to implement.</p>
651
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]652<!-- ======================================================================= -->
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]653<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]654<!-- ======================================================================= -->
655
Chris Lattneraad826b2009-09-16 18:56:12 +0000[diff] [blame]656<p><tt>__builtin_shufflevector</tt> is used to express generic vector
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]657permutation/shuffle/swizzle operations. This builtin is also very important for
658the implementation of various target-specific header files like
659<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]660</p>
661
662<p><b>Syntax:</b></p>
663
664<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]665__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]666</pre>
667
668<p><b>Examples:</b></p>
669
670<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]671 // Identity operation - return 4-element vector V1.
672 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
673
674 // "Splat" element 0 of V1 into a 4-element result.
675 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
676
677 // Reverse 4-element vector V1.
678 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
679
680 // Concatenate every other element of 4-element vectors V1 and V2.
681 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
682
683 // Concatenate every other element of 8-element vectors V1 and V2.
684 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]685</pre>
686
687<p><b>Description:</b></p>
688
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]689<p>The first two arguments to __builtin_shufflevector are vectors that have the
690same element type. The remaining arguments are a list of integers that specify
691the elements indices of the first two vectors that should be extracted and
692returned in a new vector. These element indices are numbered sequentially
693starting with the first vector, continuing into the second vector. Thus, if
694vec1 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]695</p>
696
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]697<p>The result of __builtin_shufflevector is a vector
698with the same element type as vec1/vec2 but that has an element count equal to
699the number of indices specified.
700</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]701
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]702<p>Query for this feature with __has_builtin(__builtin_shufflevector).</p>
703
704<!-- ======================================================================= -->
705<h3 id="__builtin_unreachable">__builtin_unreachable</h3>
706<!-- ======================================================================= -->
707
708<p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in
709the program cannot be reached, even if the compiler might otherwise think it
710can. This is useful to improve optimization and eliminates certain warnings.
711For example, without the <tt>__builtin_unreachable</tt> in the example below,
712the compiler assumes that the inline asm can fall through and prints a "function
713declared 'noreturn' should not return" warning.
714</p>
715
716<p><b>Syntax:</b></p>
717
718<pre>
719__builtin_unreachable()
720</pre>
721
722<p><b>Example of Use:</b></p>
723
724<pre>
725void myabort(void) __attribute__((noreturn));
726void myabort(void) {
727 asm("int3");
728 __builtin_unreachable();
729}
730</pre>
731
732<p><b>Description:</b></p>
733
734<p>The __builtin_unreachable() builtin has completely undefined behavior. Since
735it has undefined behavior, it is a statement that it is never reached and the
736optimizer can take advantage of this to produce better code. This builtin takes
737no arguments and produces a void result.
738</p>
739
740<p>Query for this feature with __has_builtin(__builtin_unreachable).</p>
741
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]742<!-- ======================================================================= -->
743<h3 id="__sync_swap">__sync_swap</h3>
744<!-- ======================================================================= -->
745
746<p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in
747memory.
748</p>
749
750<p><b>Syntax:</b></p>
751
752<pre>
753<i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...)
754</pre>
755
756<p><b>Example of Use:</b></p>
757
758<pre>
759int old_value = __sync_swap(&value, new_value);
760</pre>
761
762<p><b>Description:</b></p>
763
764<p>The __sync_swap() builtin extends the existing __sync_*() family of atomic
765intrinsics to allow code to atomically swap the current value with the new
766value. More importantly, it helps developers write more efficient and correct
767code by avoiding expensive loops around __sync_bool_compare_and_swap() or
768relying on the platform specific implementation details of
769__sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier.
770</p>
771
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]772
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]773<!-- ======================================================================= -->
774<h2 id="targetspecific">Target-Specific Extensions</h2>
775<!-- ======================================================================= -->
776
777<p>Clang supports some language features conditionally on some targets.</p>
778
779<!-- ======================================================================= -->
780<h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
781<!-- ======================================================================= -->
782
783<p>The X86 backend has these language extensions:</p>
784
785<!-- ======================================================================= -->
786<h4 id="x86-gs-segment">Memory references off the GS segment</h4>
787<!-- ======================================================================= -->
788
789<p>Annotating a pointer with address space #256 causes it to be code generated
Chris Lattnera021e7c2009-05-05 18:54:47 +0000[diff] [blame]790relative to the X86 GS segment register, and address space #257 causes it to be
791relative to the X86 FS segment. Note that this is a very very low-level
792feature that should only be used if you know what you're doing (for example in
793an OS kernel).</p>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]794
795<p>Here is an example:</p>
796
797<pre>
798#define GS_RELATIVE __attribute__((address_space(256)))
799int foo(int GS_RELATIVE *P) {
800 return *P;
801}
802</pre>
803
804<p>Which compiles to (on X86-32):</p>
805
806<pre>
807_foo:
808 movl 4(%esp), %eax
809 movl %gs:(%eax), %eax
810 ret
811</pre>
812
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]813<!-- ======================================================================= -->
814<h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
815<!-- ======================================================================= -->
816
817<p>Clang supports additional attributes that are useful for documenting program
818invariants and rules for static analysis tools. The extensions documented here
819are used by the <a
820href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
821engine</a> that is part of Clang's Analysis library.</p>
822
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]823<h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]824
825<p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
Ted Kremenek4df21142009-04-10 05:04:22 +0000[diff] [blame]826attribute. This attribute, which is typically affixed to a function prototype,
827indicates that a call to a given function never returns. Function prototypes for
828common functions like <tt>exit</tt> are typically annotated with this attribute,
829as well as a variety of common assertion handlers. Users can educate the static
830analyzer about their own custom assertion handles (thus cutting down on false
831positives due to false paths) by marking their own &quot;panic&quot; functions
832with this attribute.</p>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]833
834<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
Nick Lewycky625b5862009-06-14 04:08:08 +0000[diff] [blame]835there are special functions that for all intents and purposes should be
836considered panic functions (i.e., they are only called when an internal program
837error occurs) but may actually return so that the program can fail gracefully.
838The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
839as being interpreted as &quot;no return&quot; functions by the analyzer (thus
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]840pruning bogus paths) but will not affect compilation (as in the case of
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]841<tt>noreturn</tt>).</p>
842
843<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]844same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]845placed at the end of function prototypes:</p>
846
847<pre>
848 void foo() <b>__attribute__((analyzer_noreturn))</b>;
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]849</pre>
850
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]851<p>Query for this feature with
852<tt>__has_attribute(analyzer_noreturn)</tt>.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]853
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]854<h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3>
855
856<p>Many methods in Objective-C have conventional meanings determined
857by their selectors. For the purposes of static analysis, it is
858sometimes useful to be able to mark a method as having a particular
859conventional meaning despite not having the right selector, or as not
860having the conventional meaning that its selector would suggest.
861For these use cases, we provide an attribute to specifically describe
862the <q>method family</q> that a method belongs to.</p>
863
864<p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>,
865where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>,
866<tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>. This attribute
867can only be placed at the end of a method declaration:</p>
868
869<pre>
870 - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>;
871</pre>
872
873<p>Users who do not wish to change the conventional meaning of a
874method, and who merely want to document its non-standard retain and
875release semantics, should use the
876<a href="#attr_retain_release">retaining behavior attributes</a>
877described below.</p>
878
879<p>Query for this feature with
880<tt>__has_attribute(objc_method_family)</tt>.</p>
881
882<h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]883
884<p>In Objective-C, functions and methods are generally assumed to take
885and return objects with +0 retain counts, with some exceptions for
886special methods like <tt>+alloc</tt> and <tt>init</tt>. However,
887there are exceptions, and so Clang provides attributes to allow these
888exceptions to be documented, which helps the analyzer find leaks (and
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]889ignore non-leaks). Some exceptions may be better described using
890the <a href="#attr_method_family"><tt>objc_method_family</tt></a>
891attribute instead.</p>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]892
893<p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>,
894<tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>,
895and <tt>cf_returns_not_retained</tt> attributes can be placed on
896methods and functions that return Objective-C or CoreFoundation
897objects. They are commonly placed at the end of a function prototype
898or method declaration:</p>
899
900<pre>
901 id foo() <b>__attribute__((ns_returns_retained))</b>;
902
903 - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>;
904</pre>
905
906<p>The <tt>*_returns_retained</tt> attributes specify that the
907returned object has a +1 retain count.
908The <tt>*_returns_not_retained</tt> attributes specify that the return
909object has a +0 retain count, even if the normal convention for its
910selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the
911returned object is +0, but is guaranteed to live at least as long as the
912next flush of an autorelease pool.</p>
913
914<p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt>
915attributes can be placed on an parameter declaration; they specify
916that the argument is expected to have a +1 retain count, which will be
917balanced in some way by the function or method.
918The <tt>ns_consumes_self</tt> attribute can only be placed on an
919Objective-C method; it specifies that the method expects
920its <tt>self</tt> parameter to have a +1 retain count, which it will
921balance in some way.</p>
922
923<pre>
924 void <b>foo(__attribute__((ns_consumed))</b> NSString *string);
925
926 - (void) bar <b>__attribute__((ns_consumes_self))</b>;
927 - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x;
928</pre>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]929
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]930<p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>,
931<tt>__has_attribute(ns_returns_retained)</tt>, etc.</p>
932
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]933</div>
934</body>
935</html>