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