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