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