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