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