Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 0750800623dc6d14c4c0c721996ffd4210fcdff3 / . / docs / LanguageExtensions.html
blob: 8f412c63653b3579e1171bcac4aff227e5c1e234 [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,
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]422<tt>auto</tt> will instead be a storage class specifier, as in C or C++98.
423Clang does not currently implement this feature.</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_variadic_templates">C++0x variadic templates</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]426
427<p>Use <tt>__has_feature(cxx_variadic_templates)</tt> to determine if support
Douglas Gregor83d77812011-01-19 23:15:20 +0000[diff] [blame]428for variadic templates is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]429
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]430<h3 id="cxx_inline_namespaces">C++0x inline namespaces</h3>
431
432<p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> to determine if support for
433inline namespaces is enabled.</p>
434
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]435<h3 id="cxx_trailing_return">C++0x trailing return type</h3>
436
437<p>Use <tt>__has_feature(cxx_trailing_return)</tt> to determine if support for
438the alternate function declaration syntax with trailing return type is enabled.</p>
439
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]440<h3 id="cxx_strong_enums">C++0x strongly typed enumerations</h3>
441
442<p>Use <tt>__has_feature(cxx_strong_enums)</tt> to determine if support for
443strongly typed, scoped enumerations is enabled.</p>
444
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]445<!-- ======================================================================= -->
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]446<h2 id="checking_type_traits">Checks for Type Traits</h2>
447<!-- ======================================================================= -->
448
449<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:
450<blockquote>
451<pre>
452#if __has_feature(is_convertible_to)
453template&lt;typename From, typename To&gt;
454struct is_convertible_to {
455 static const bool value = __is_convertible_to(From, To);
456};
457#else
458// Emulate type trait
459#endif
460</pre>
461</blockquote>
462
463<p>The following type traits are supported by Clang:</p>
464<ul>
465 <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li>
466 <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li>
467 <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li>
468 <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li>
469 <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li>
470 <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li>
471 <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li>
472 <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li>
473 <li><code>__is_abstract</code> (GNU, Microsoft)</li>
474 <li><code>__is_base_of</code> (GNU, Microsoft)</li>
475 <li><code>__is_class</code> (GNU, Microsoft)</li>
476 <li><code>__is_convertible_to</code> (Microsoft)</li>
477 <li><code>__is_empty</code> (GNU, Microsoft)</li>
478 <li><code>__is_enum</code> (GNU, Microsoft)</li>
479 <li><code>__is_pod</code> (GNU, Microsoft)</li>
480 <li><code>__is_polymorphic</code> (GNU, Microsoft)</li>
481 <li><code>__is_union</code> (GNU, Microsoft)</li>
482 <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li>
483</ul>
484
485<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]486<h2 id="blocks">Blocks</h2>
487<!-- ======================================================================= -->
488
Chris Lattnera7dbdf52009-03-09 07:03:22 +0000[diff] [blame]489<p>The syntax and high level language feature description is in <a
490href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
491details for the clang implementation are in <a
Chris Lattner5d7650b2010-03-16 21:43:03 +0000[diff] [blame]492href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]493
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]494
495<p>Query for this feature with __has_feature(blocks).</p>
496
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]497<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]498<h2 id="overloading-in-c">Function Overloading in C</h2>
499<!-- ======================================================================= -->
500
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]501<p>Clang provides support for C++ function overloading in C. Function
502overloading in C is introduced using the <tt>overloadable</tt> attribute. For
503example, one might provide several overloaded versions of a <tt>tgsin</tt>
504function that invokes the appropriate standard function computing the sine of a
505value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
506precision:</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]507
508<blockquote>
509<pre>
510#include &lt;math.h&gt;
511float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
512double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
513long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
514</pre>
515</blockquote>
516
517<p>Given these declarations, one can call <tt>tgsin</tt> with a
518<tt>float</tt> value to receive a <tt>float</tt> result, with a
519<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
520overloading in C follows the rules of C++ function overloading to pick
521the best overload given the call arguments, with a few C-specific
522semantics:</p>
523<ul>
524 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
525 double</tt> is ranked as a floating-point promotion (per C99) rather
526 than as a floating-point conversion (as in C++).</li>
527
528 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
529 <tt>U*</tt> is considered a pointer conversion (with conversion
530 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
531
532 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
533 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
534 conversion is given "conversion" rank.</li>
535</ul>
536
537<p>The declaration of <tt>overloadable</tt> functions is restricted to
538function declarations and definitions. Most importantly, if any
539function with a given name is given the <tt>overloadable</tt>
540attribute, then all function declarations and definitions with that
541name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]542attribute. This rule even applies to redeclarations of functions whose original
543declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]544
545<blockquote>
546<pre>
547int f(int) __attribute__((overloadable));
548float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
549
550int g(int) __attribute__((overloadable));
551int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
552</pre>
553</blockquote>
554
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]555<p>Functions marked <tt>overloadable</tt> must have
556prototypes. Therefore, the following code is ill-formed:</p>
557
558<blockquote>
559<pre>
560int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
561</pre>
562</blockquote>
563
564<p>However, <tt>overloadable</tt> functions are allowed to use a
565ellipsis 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>
566
567<blockquote>
568<pre>
Chris Lattner02246802009-02-18 22:27:46 +0000[diff] [blame]569void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]570</pre>
571</blockquote>
572
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]573<p>Functions declared with the <tt>overloadable</tt> attribute have
574their names mangled according to the same rules as C++ function
575names. For example, the three <tt>tgsin</tt> functions in our
576motivating example get the mangled names <tt>_Z5tgsinf</tt>,
Chris Lattner71b48d62010-11-28 18:19:13 +0000[diff] [blame]577<tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]578caveats to this use of name mangling:</p>
579
580<ul>
581
582 <li>Future versions of Clang may change the name mangling of
583 functions overloaded in C, so you should not depend on an specific
584 mangling. To be completely safe, we strongly urge the use of
585 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
586
587 <li>The <tt>overloadable</tt> attribute has almost no meaning when
588 used in C++, because names will already be mangled and functions are
589 already overloadable. However, when an <tt>overloadable</tt>
590 function occurs within an <tt>extern "C"</tt> linkage specification,
591 it's name <i>will</i> be mangled in the same way as it would in
592 C.</li>
593</ul>
594
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]595<p>Query for this feature with __has_feature(attribute_overloadable).</p>
596
597
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]598<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]599<h2 id="builtins">Builtin Functions</h2>
600<!-- ======================================================================= -->
601
602<p>Clang supports a number of builtin library functions with the same syntax as
603GCC, including things like <tt>__builtin_nan</tt>,
604<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
605<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
606addition to the GCC builtins, Clang supports a number of builtins that GCC does
607not, which are listed here.</p>
608
609<p>Please note that Clang does not and will not support all of the GCC builtins
610for vector operations. Instead of using builtins, you should use the functions
611defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
612define portable wrappers for these. Many of the Clang versions of these
613functions are implemented directly in terms of <a href="#vectors">extended
614vector support</a> instead of builtins, in order to reduce the number of
615builtins that we need to implement.</p>
616
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]617<!-- ======================================================================= -->
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]618<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]619<!-- ======================================================================= -->
620
Chris Lattneraad826b2009-09-16 18:56:12 +0000[diff] [blame]621<p><tt>__builtin_shufflevector</tt> is used to express generic vector
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]622permutation/shuffle/swizzle operations. This builtin is also very important for
623the implementation of various target-specific header files like
624<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]625</p>
626
627<p><b>Syntax:</b></p>
628
629<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]630__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]631</pre>
632
633<p><b>Examples:</b></p>
634
635<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]636 // Identity operation - return 4-element vector V1.
637 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
638
639 // "Splat" element 0 of V1 into a 4-element result.
640 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
641
642 // Reverse 4-element vector V1.
643 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
644
645 // Concatenate every other element of 4-element vectors V1 and V2.
646 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
647
648 // Concatenate every other element of 8-element vectors V1 and V2.
649 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]650</pre>
651
652<p><b>Description:</b></p>
653
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]654<p>The first two arguments to __builtin_shufflevector are vectors that have the
655same element type. The remaining arguments are a list of integers that specify
656the elements indices of the first two vectors that should be extracted and
657returned in a new vector. These element indices are numbered sequentially
658starting with the first vector, continuing into the second vector. Thus, if
659vec1 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]660</p>
661
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]662<p>The result of __builtin_shufflevector is a vector
663with the same element type as vec1/vec2 but that has an element count equal to
664the number of indices specified.
665</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]666
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]667<p>Query for this feature with __has_builtin(__builtin_shufflevector).</p>
668
669<!-- ======================================================================= -->
670<h3 id="__builtin_unreachable">__builtin_unreachable</h3>
671<!-- ======================================================================= -->
672
673<p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in
674the program cannot be reached, even if the compiler might otherwise think it
675can. This is useful to improve optimization and eliminates certain warnings.
676For example, without the <tt>__builtin_unreachable</tt> in the example below,
677the compiler assumes that the inline asm can fall through and prints a "function
678declared 'noreturn' should not return" warning.
679</p>
680
681<p><b>Syntax:</b></p>
682
683<pre>
684__builtin_unreachable()
685</pre>
686
687<p><b>Example of Use:</b></p>
688
689<pre>
690void myabort(void) __attribute__((noreturn));
691void myabort(void) {
692 asm("int3");
693 __builtin_unreachable();
694}
695</pre>
696
697<p><b>Description:</b></p>
698
699<p>The __builtin_unreachable() builtin has completely undefined behavior. Since
700it has undefined behavior, it is a statement that it is never reached and the
701optimizer can take advantage of this to produce better code. This builtin takes
702no arguments and produces a void result.
703</p>
704
705<p>Query for this feature with __has_builtin(__builtin_unreachable).</p>
706
707
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]708<!-- ======================================================================= -->
709<h2 id="targetspecific">Target-Specific Extensions</h2>
710<!-- ======================================================================= -->
711
712<p>Clang supports some language features conditionally on some targets.</p>
713
714<!-- ======================================================================= -->
715<h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
716<!-- ======================================================================= -->
717
718<p>The X86 backend has these language extensions:</p>
719
720<!-- ======================================================================= -->
721<h4 id="x86-gs-segment">Memory references off the GS segment</h4>
722<!-- ======================================================================= -->
723
724<p>Annotating a pointer with address space #256 causes it to be code generated
Chris Lattnera021e7c2009-05-05 18:54:47 +0000[diff] [blame]725relative to the X86 GS segment register, and address space #257 causes it to be
726relative to the X86 FS segment. Note that this is a very very low-level
727feature that should only be used if you know what you're doing (for example in
728an OS kernel).</p>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]729
730<p>Here is an example:</p>
731
732<pre>
733#define GS_RELATIVE __attribute__((address_space(256)))
734int foo(int GS_RELATIVE *P) {
735 return *P;
736}
737</pre>
738
739<p>Which compiles to (on X86-32):</p>
740
741<pre>
742_foo:
743 movl 4(%esp), %eax
744 movl %gs:(%eax), %eax
745 ret
746</pre>
747
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]748<!-- ======================================================================= -->
749<h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
750<!-- ======================================================================= -->
751
752<p>Clang supports additional attributes that are useful for documenting program
753invariants and rules for static analysis tools. The extensions documented here
754are used by the <a
755href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
756engine</a> that is part of Clang's Analysis library.</p>
757
758<!-- ======================================================================= -->
759<h3 id="analyzerattributes">Analyzer Attributes</h3>
760<!-- ======================================================================= -->
761
762<h4 id="attr_analyzer_noreturn"><tt>analyzer_noreturn</tt></h4>
763
764<p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
Ted Kremenek4df21142009-04-10 05:04:22 +0000[diff] [blame]765attribute. This attribute, which is typically affixed to a function prototype,
766indicates that a call to a given function never returns. Function prototypes for
767common functions like <tt>exit</tt> are typically annotated with this attribute,
768as well as a variety of common assertion handlers. Users can educate the static
769analyzer about their own custom assertion handles (thus cutting down on false
770positives due to false paths) by marking their own &quot;panic&quot; functions
771with this attribute.</p>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]772
773<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
Nick Lewycky625b5862009-06-14 04:08:08 +0000[diff] [blame]774there are special functions that for all intents and purposes should be
775considered panic functions (i.e., they are only called when an internal program
776error occurs) but may actually return so that the program can fail gracefully.
777The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
778as being interpreted as &quot;no return&quot; functions by the analyzer (thus
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]779pruning bogus paths) but will not affect compilation (as in the case of
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]780<tt>noreturn</tt>).</p>
781
782<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]783same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]784placed at the end of function prototypes:</p>
785
786<pre>
787 void foo() <b>__attribute__((analyzer_noreturn))</b>;
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]788</pre>
789
790<p>Query for this feature with __has_feature(attribute_analyzer_noreturn).</p>
791
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]792<h4 id="attr_retain_release">Objective-C retaining behavior attributes</h4>
793
794<p>In Objective-C, functions and methods are generally assumed to take
795and return objects with +0 retain counts, with some exceptions for
796special methods like <tt>+alloc</tt> and <tt>init</tt>. However,
797there are exceptions, and so Clang provides attributes to allow these
798exceptions to be documented, which helps the analyzer find leaks (and
799ignore non-leaks).</p>
800
801<p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>,
802<tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>,
803and <tt>cf_returns_not_retained</tt> attributes can be placed on
804methods and functions that return Objective-C or CoreFoundation
805objects. They are commonly placed at the end of a function prototype
806or method declaration:</p>
807
808<pre>
809 id foo() <b>__attribute__((ns_returns_retained))</b>;
810
811 - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>;
812</pre>
813
814<p>The <tt>*_returns_retained</tt> attributes specify that the
815returned object has a +1 retain count.
816The <tt>*_returns_not_retained</tt> attributes specify that the return
817object has a +0 retain count, even if the normal convention for its
818selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the
819returned object is +0, but is guaranteed to live at least as long as the
820next flush of an autorelease pool.</p>
821
822<p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt>
823attributes can be placed on an parameter declaration; they specify
824that the argument is expected to have a +1 retain count, which will be
825balanced in some way by the function or method.
826The <tt>ns_consumes_self</tt> attribute can only be placed on an
827Objective-C method; it specifies that the method expects
828its <tt>self</tt> parameter to have a +1 retain count, which it will
829balance in some way.</p>
830
831<pre>
832 void <b>foo(__attribute__((ns_consumed))</b> NSString *string);
833
834 - (void) bar <b>__attribute__((ns_consumes_self))</b>;
835 - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x;
836</pre>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]837
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]838</div>
839</body>
840</html>