Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 4d53a53b81fcdf84346a4ac772d101423c9f5a41 / . / docs / LanguageExtensions.html
blob: 1bccdbd2cc777e4cac293f58e06cec3c75f6c8b6 [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>
24<li><a href="#builtins">Builtin Functions</a>
25 <ul>
26 <li><a href="#__builtin_overload">__builtin_overload</a></li>
27 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
28 </ul>
29</li>
30</ul>
31
32
33<!-- ======================================================================= -->
34<h2 id="intro">Introduction</h2>
35<!-- ======================================================================= -->
36
37<p>This document describes the language extensions provided by Clang. In
38addition to the langauge extensions listed here, Clang aims to support a broad
39range of GCC extensions. Please see the <a
40href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
41more information on these extensions.</p>
42
43<!-- ======================================================================= -->
44<h2 id="vectors">Vectors and Extended Vectors</h2>
45<!-- ======================================================================= -->
46
47<p>Supports the GCC vector extensions, plus some stuff like V[1]. ext_vector
48with V.xyzw syntax and other tidbits. See also <a
49href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
50
51<!-- ======================================================================= -->
52<h2 id="blocks">Blocks</h2>
53<!-- ======================================================================= -->
54
55<p>The idea, syntax, and semantics.</p>
56
57<!-- ======================================================================= -->
58<h2 id="builtins">Builtin Functions</h2>
59<!-- ======================================================================= -->
60
61<p>Clang supports a number of builtin library functions with the same syntax as
62GCC, including things like <tt>__builtin_nan</tt>,
63<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
64<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
65addition to the GCC builtins, Clang supports a number of builtins that GCC does
66not, which are listed here.</p>
67
68<p>Please note that Clang does not and will not support all of the GCC builtins
69for vector operations. Instead of using builtins, you should use the functions
70defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
71define portable wrappers for these. Many of the Clang versions of these
72functions are implemented directly in terms of <a href="#vectors">extended
73vector support</a> instead of builtins, in order to reduce the number of
74builtins that we need to implement.</p>
75
76
77<!-- ======================================================================= -->
78<h3 id="__builtin_overload">__builtin_overload</h3>
79<!-- ======================================================================= -->
80
81<p><tt>__builtin_overload</tt> is used to implement type-generic "overloaded"
82functions in C. This builtin is used to implement the <tt>&lt;tgmath.h&gt;</tt>
83header file, but is intended to be usable for a broad variety of other similar
84situations, like the <tt>&lt;altivec.h&gt;</tt> header.
85</p>
86
87<p><b>Syntax:</b></p>
88
89<pre>
90__builtin_overload(FnNameStr, PromotionRuleStr, NumArgs, arg1, arg2, ...
91 overloadcandidate1, overloadcandidate2, ...)
92</pre>
93
94<p><b>Examples:</b></p>
95
96<pre>
97#define sin(x) \
98 (__builtin_overload("sin", "tgmath", 1, x, sinf, sin, sinl,
99 csinf, csin, csinl)(x))
100#define fma(x,y,z) \
101 (__builtin_overload("fma", "tgmath", 3, x, y, z, fmaf, fma, fmal)(x,y,z))
102#define ldexp(x, y) \
103 (__builtin_overload("ldexp", "tgmath1", 2, x, 0, ldexpf, ldexp, ldexpl)(x,y))
104</pre>
105
106<p><b>Description:</b></p>
107
108<p>The first argument to __builtin_overload is a string that is the name of the
109"function" being implemented. This is used to produce diagnostics that make
110sense to the user. For example, if you accidentally pass a pointer argument to
111"sin" in GCC, it emits 6 errors about incompatible types. This name allows
112Clang to diagnose the error in a way the user can understand.
113</p>
114
115<p>The second argument is a string that indicates a set of promotion rules to
116apply to the arguments before prototype matching occurs. The currently
117supported rules are:</p>
118
119<dl>
120 <dt>tgmath</dt>
121 <dd>Follow the rules of C99 7.22 to determine a single common type, and use it
122 for every argument.</dd>
123 <dt>tgmath1</dt>
124 <dd>Follow the rules of C99 7.22 to determine a single common type of just the
125 first argument (e.g. treat ints as doubles).</dd>
126</dl>
127
128<p>The third argument is an integer that specifies the arity of the function
129 being overloaded. After this are N expression arguments which are promoted
130 according to the rules specified by the promotion rule string.</p>
131
132<p>The final arguments are functions or function pointers with different
133 signatures. __builtin_overload will match and evaluate to the first function
134 pointer whose signature is compatible and does not cause value truncation of
135 any arguments to the function.</p>
136
137
138<!-- ======================================================================= -->
139<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
140<!-- ======================================================================= -->
141
142<p>todo describe me.</p>
143
144
145</div>
146</body>
147</html>