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