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