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