Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / 148772a841cae6f32db16d890e788b92a763bb3f / . / docs / LanguageExtensions.html
blob: 55fb6158344f9d2c868bfcc22f41bb191b59f36d [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>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]23<li><a href="#builtinmacros">Builtin Macros</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]24<li><a href="#vectors">Vectors and Extended Vectors</a></li>
25<li><a href="#blocks">Blocks</a></li>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]26<li><a href="#overloading-in-c">Function Overloading in C</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]27<li><a href="#builtins">Builtin Functions</a>
28 <ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]29 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
30 </ul>
31</li>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]32<li><a href="#targetspecific">Target-Specific Extensions</a>
33 <ul>
34 <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li>
35 </ul>
36</li>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]37<li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a>
38 <ul>
39 <li><a href="#analyzerattributes">Analyzer Attributes</a></li>
40 </ul>
41</li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]42</ul>
43
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]44<!-- ======================================================================= -->
45<h2 id="intro">Introduction</h2>
46<!-- ======================================================================= -->
47
48<p>This document describes the language extensions provided by Clang. In
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame^]49addition to the language extensions listed here, Clang aims to support a broad
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]50range of GCC extensions. Please see the <a
51href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
52more information on these extensions.</p>
53
54<!-- ======================================================================= -->
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame^]55<h2 id="feature_check">Feature Checking Macros</h2>
56<!-- ======================================================================= -->
57
58<p>Language extensions can be very useful, but only if you know you can depend
59on them. In order to allow fine-grain features checks, we support two builtin
60function-like macros. This allows you to directly test for a feature in your
61code without having to resort to something like autoconf or fragile "compiler
62version checks".</p>
63
64<!-- ======================================================================= -->
65<h3 id="__has_builtin">__has_builtin</h3>
66<!-- ======================================================================= -->
67
68<p>This function-like macro takes a single identifier argument that is the name
69of a builtin function. It evaluates to 1 if the builtin is supported or 0 if
70not. It can be used like this:</p>
71
72<blockquote>
73<pre>
74#ifndef __has_builtin // Optional of course.
75 #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
76#endif
77
78...
79#if __has_builtin(__builtin_trap)
80 __builtin_trap();
81#else
82 abort();
83#endif
84...
85</pre>
86</blockquote>
87
88
89<!-- ======================================================================= -->
90<h3 id="__has_feature">__has_feature</h3>
91<!-- ======================================================================= -->
92
93<p>This function-like macro takes a single identifier argument that is the name
94of a feature. It evaluates to 1 if the feature is supported or 0 if not. It
95can be used like this:</p>
96
97<blockquote>
98<pre>
99#ifndef __has_feature // Optional of course.
100 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
101#endif
102
103...
104#if __has_feature(attribute_overloadable) || \
105 __has_feature(blocks)
106...
107#endif
108...
109</pre>
110</blockquote>
111
112<p>The feature tag is described along with the language feature below.</p>
113
114
115<!-- ======================================================================= -->
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]116<h2 id="builtinmacros">Builtin Macros</h2>
117<!-- ======================================================================= -->
118
119<p>__BASE_FILE__, __INCLUDE_LEVEL__, __TIMESTAMP__, __COUNTER__</p>
120
121<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]122<h2 id="vectors">Vectors and Extended Vectors</h2>
123<!-- ======================================================================= -->
124
125<p>Supports the GCC vector extensions, plus some stuff like V[1]. ext_vector
126with V.xyzw syntax and other tidbits. See also <a
127href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
128
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame^]129<p>Query for this feature with __has_feature(attribute_ext_vector_type).</p>
130
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]131<!-- ======================================================================= -->
132<h2 id="blocks">Blocks</h2>
133<!-- ======================================================================= -->
134
Chris Lattnera7dbdf52009-03-09 07:03:22 +0000[diff] [blame]135<p>The syntax and high level language feature description is in <a
136href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
137details for the clang implementation are in <a
138href="BlockImplementation.txt">BlockImplementation.txt</a>.</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]139
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame^]140
141<p>Query for this feature with __has_feature(blocks).</p>
142
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]143<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]144<h2 id="overloading-in-c">Function Overloading in C</h2>
145<!-- ======================================================================= -->
146
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]147<p>Clang provides support for C++ function overloading in C. Function
148overloading in C is introduced using the <tt>overloadable</tt> attribute. For
149example, one might provide several overloaded versions of a <tt>tgsin</tt>
150function that invokes the appropriate standard function computing the sine of a
151value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
152precision:</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]153
154<blockquote>
155<pre>
156#include &lt;math.h&gt;
157float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
158double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
159long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
160</pre>
161</blockquote>
162
163<p>Given these declarations, one can call <tt>tgsin</tt> with a
164<tt>float</tt> value to receive a <tt>float</tt> result, with a
165<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
166overloading in C follows the rules of C++ function overloading to pick
167the best overload given the call arguments, with a few C-specific
168semantics:</p>
169<ul>
170 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
171 double</tt> is ranked as a floating-point promotion (per C99) rather
172 than as a floating-point conversion (as in C++).</li>
173
174 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
175 <tt>U*</tt> is considered a pointer conversion (with conversion
176 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
177
178 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
179 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
180 conversion is given "conversion" rank.</li>
181</ul>
182
183<p>The declaration of <tt>overloadable</tt> functions is restricted to
184function declarations and definitions. Most importantly, if any
185function with a given name is given the <tt>overloadable</tt>
186attribute, then all function declarations and definitions with that
187name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]188attribute. This rule even applies to redeclarations of functions whose original
189declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]190
191<blockquote>
192<pre>
193int f(int) __attribute__((overloadable));
194float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
195
196int g(int) __attribute__((overloadable));
197int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
198</pre>
199</blockquote>
200
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]201<p>Functions marked <tt>overloadable</tt> must have
202prototypes. Therefore, the following code is ill-formed:</p>
203
204<blockquote>
205<pre>
206int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
207</pre>
208</blockquote>
209
210<p>However, <tt>overloadable</tt> functions are allowed to use a
211ellipsis 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>
212
213<blockquote>
214<pre>
Chris Lattner02246802009-02-18 22:27:46 +0000[diff] [blame]215void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]216</pre>
217</blockquote>
218
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]219<p>Functions declared with the <tt>overloadable</tt> attribute have
220their names mangled according to the same rules as C++ function
221names. For example, the three <tt>tgsin</tt> functions in our
222motivating example get the mangled names <tt>_Z5tgsinf</tt>,
223<tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
224caveats to this use of name mangling:</p>
225
226<ul>
227
228 <li>Future versions of Clang may change the name mangling of
229 functions overloaded in C, so you should not depend on an specific
230 mangling. To be completely safe, we strongly urge the use of
231 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
232
233 <li>The <tt>overloadable</tt> attribute has almost no meaning when
234 used in C++, because names will already be mangled and functions are
235 already overloadable. However, when an <tt>overloadable</tt>
236 function occurs within an <tt>extern "C"</tt> linkage specification,
237 it's name <i>will</i> be mangled in the same way as it would in
238 C.</li>
239</ul>
240
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame^]241<p>Query for this feature with __has_feature(attribute_overloadable).</p>
242
243
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]244<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]245<h2 id="builtins">Builtin Functions</h2>
246<!-- ======================================================================= -->
247
248<p>Clang supports a number of builtin library functions with the same syntax as
249GCC, including things like <tt>__builtin_nan</tt>,
250<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
251<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
252addition to the GCC builtins, Clang supports a number of builtins that GCC does
253not, which are listed here.</p>
254
255<p>Please note that Clang does not and will not support all of the GCC builtins
256for vector operations. Instead of using builtins, you should use the functions
257defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
258define portable wrappers for these. Many of the Clang versions of these
259functions are implemented directly in terms of <a href="#vectors">extended
260vector support</a> instead of builtins, in order to reduce the number of
261builtins that we need to implement.</p>
262
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]263<!-- ======================================================================= -->
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]264<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]265<!-- ======================================================================= -->
266
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]267<p><tt>__builtin_shufflevector</tt> is used to expression generic vector
268permutation/shuffle/swizzle operations. This builtin is also very important for
269the implementation of various target-specific header files like
270<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]271</p>
272
273<p><b>Syntax:</b></p>
274
275<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]276__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]277</pre>
278
279<p><b>Examples:</b></p>
280
281<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]282 // Identity operation - return 4-element vector V1.
283 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
284
285 // "Splat" element 0 of V1 into a 4-element result.
286 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
287
288 // Reverse 4-element vector V1.
289 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
290
291 // Concatenate every other element of 4-element vectors V1 and V2.
292 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
293
294 // Concatenate every other element of 8-element vectors V1 and V2.
295 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]296</pre>
297
298<p><b>Description:</b></p>
299
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]300<p>The first two arguments to __builtin_shufflevector are vectors that have the
301same element type. The remaining arguments are a list of integers that specify
302the elements indices of the first two vectors that should be extracted and
303returned in a new vector. These element indices are numbered sequentially
304starting with the first vector, continuing into the second vector. Thus, if
305vec1 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]306</p>
307
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]308<p>The result of __builtin_shufflevector is a vector
309with the same element type as vec1/vec2 but that has an element count equal to
310the number of indices specified.
311</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]312
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]313<!-- ======================================================================= -->
314<h2 id="targetspecific">Target-Specific Extensions</h2>
315<!-- ======================================================================= -->
316
317<p>Clang supports some language features conditionally on some targets.</p>
318
319<!-- ======================================================================= -->
320<h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
321<!-- ======================================================================= -->
322
323<p>The X86 backend has these language extensions:</p>
324
325<!-- ======================================================================= -->
326<h4 id="x86-gs-segment">Memory references off the GS segment</h4>
327<!-- ======================================================================= -->
328
329<p>Annotating a pointer with address space #256 causes it to be code generated
Chris Lattnera021e7c2009-05-05 18:54:47 +0000[diff] [blame]330relative to the X86 GS segment register, and address space #257 causes it to be
331relative to the X86 FS segment. Note that this is a very very low-level
332feature that should only be used if you know what you're doing (for example in
333an OS kernel).</p>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]334
335<p>Here is an example:</p>
336
337<pre>
338#define GS_RELATIVE __attribute__((address_space(256)))
339int foo(int GS_RELATIVE *P) {
340 return *P;
341}
342</pre>
343
344<p>Which compiles to (on X86-32):</p>
345
346<pre>
347_foo:
348 movl 4(%esp), %eax
349 movl %gs:(%eax), %eax
350 ret
351</pre>
352
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]353<!-- ======================================================================= -->
354<h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
355<!-- ======================================================================= -->
356
357<p>Clang supports additional attributes that are useful for documenting program
358invariants and rules for static analysis tools. The extensions documented here
359are used by the <a
360href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
361engine</a> that is part of Clang's Analysis library.</p>
362
363<!-- ======================================================================= -->
364<h3 id="analyzerattributes">Analyzer Attributes</h3>
365<!-- ======================================================================= -->
366
367<h4 id="attr_analyzer_noreturn"><tt>analyzer_noreturn</tt></h4>
368
369<p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
Ted Kremenek4df21142009-04-10 05:04:22 +0000[diff] [blame]370attribute. This attribute, which is typically affixed to a function prototype,
371indicates that a call to a given function never returns. Function prototypes for
372common functions like <tt>exit</tt> are typically annotated with this attribute,
373as well as a variety of common assertion handlers. Users can educate the static
374analyzer about their own custom assertion handles (thus cutting down on false
375positives due to false paths) by marking their own &quot;panic&quot; functions
376with this attribute.</p>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]377
378<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
379there are special functions that for all intensive purposes should be considered
380panic functions (i.e., they are only called when an internal program error
381occurs) but may actually return so that the program can fail gracefully. The
382<tt>analyzer_noreturn</tt> attribute allows one to annotate such functions as
383being interpreted as &quot;no return&quot; functions by the analyzer (thus
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]384pruning bogus paths) but will not affect compilation (as in the case of
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]385<tt>noreturn</tt>).</p>
386
387<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]388same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]389placed at the end of function prototypes:</p>
390
391<pre>
392 void foo() <b>__attribute__((analyzer_noreturn))</b>;
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame^]393</pre>
394
395<p>Query for this feature with __has_feature(attribute_analyzer_noreturn).</p>
396
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]397
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]398</div>
399</body>
400</html>