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