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