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