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