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