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