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