docs/LanguageExtensions.html

   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">
   7 td {
   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="#feature_check">Feature Checking Macros</a></li>
  23 <li><a href="#builtinmacros">Builtin Macros</a></li>
  24 <li><a href="#vectors">Vectors and Extended Vectors</a></li>
  25 <li><a href="#blocks">Blocks</a></li>
  26 <li><a href="#overloading-in-c">Function Overloading in C</a></li>
  27 <li><a href="#builtins">Builtin Functions</a>
  28   <ul>
  29   <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
  30   </ul>
  31 </li>
  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>
  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>
  42 </ul>
  43
  44 <!-- ======================================================================= -->
  45 <h2 id="intro">Introduction</h2>
  46 <!-- ======================================================================= -->
  47
  48 <p>This document describes the language extensions provided by Clang.  In
  49 addition to the language extensions listed here, Clang aims to support a broad
  50 range of GCC extensions.  Please see the <a
  51 href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
  52 more information on these extensions.</p>
  53
  54 <!-- ======================================================================= -->
  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
  59 on them.  In order to allow fine-grain features checks, we support two builtin
  60 function-like macros.  This allows you to directly test for a feature in your
  61 code without having to resort to something like autoconf or fragile "compiler
  62 version 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
  69 of a builtin function.  It evaluates to 1 if the builtin is supported or 0 if
  70 not.  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
  94 of a feature.  It evaluates to 1 if the feature is supported or 0 if not.  It
  95 can 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 <!-- ======================================================================= -->
 116 <h2 id="builtinmacros">Builtin Macros</h2>
 117 <!-- ======================================================================= -->
 118
 119 <p>__BASE_FILE__, __INCLUDE_LEVEL__, __TIMESTAMP__, __COUNTER__</p>
 120
 121 <!-- ======================================================================= -->
 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
 126 with V.xyzw syntax and other tidbits.  See also <a
 127 href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
 128
 129 <p>Query for this feature with __has_feature(attribute_ext_vector_type).</p>
 130
 131 <!-- ======================================================================= -->
 132 <h2 id="blocks">Blocks</h2>
 133 <!-- ======================================================================= -->
 134
 135 <p>The syntax and high level language feature description is in <a
 136 href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>.  Implementation and ABI
 137 details for the clang implementation are in <a
 138 href="BlockImplementation.txt">BlockImplementation.txt</a>.</p>
 139
 140
 141 <p>Query for this feature with __has_feature(blocks).</p>
 142
 143 <!-- ======================================================================= -->
 144 <h2 id="overloading-in-c">Function Overloading in C</h2>
 145 <!-- ======================================================================= -->
 146
 147 <p>Clang provides support for C++ function overloading in C. Function
 148 overloading in C is introduced using the <tt>overloadable</tt> attribute. For
 149 example, one might provide several overloaded versions of a <tt>tgsin</tt>
 150 function that invokes the appropriate standard function computing the sine of a
 151 value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
 152 precision:</p>
 153
 154 <blockquote>
 155 <pre>
 156 #include &lt;math.h&gt;
 157 float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
 158 double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
 159 long 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
 166 overloading in C follows the rules of C++ function overloading to pick
 167 the best overload given the call arguments, with a few C-specific
 168 semantics:</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
 184 function declarations and definitions. Most importantly, if any
 185 function with a given name is given the <tt>overloadable</tt>
 186 attribute, then all function declarations and definitions with that
 187 name (and in that scope) must have the <tt>overloadable</tt>
 188 attribute. This rule even applies to redeclarations of functions whose original
 189 declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
 190
 191 <blockquote>
 192 <pre>
 193 int f(int) __attribute__((overloadable));
 194 float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
 195
 196 int g(int) __attribute__((overloadable));
 197 int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
 198 </pre>
 199 </blockquote>
 200
 201 <p>Functions marked <tt>overloadable</tt> must have
 202 prototypes. Therefore, the following code is ill-formed:</p>
 203
 204 <blockquote>
 205 <pre>
 206 int 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
 211 ellipsis 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>
 215 void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
 216 </pre>
 217 </blockquote>
 218
 219 <p>Functions declared with the <tt>overloadable</tt> attribute have
 220 their names mangled according to the same rules as C++ function
 221 names. For example, the three <tt>tgsin</tt> functions in our
 222 motivating example get the mangled names <tt>_Z5tgsinf</tt>,
 223 <tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
 224 caveats 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
 241 <p>Query for this feature with __has_feature(attribute_overloadable).</p>
 242
 243
 244 <!-- ======================================================================= -->
 245 <h2 id="builtins">Builtin Functions</h2>
 246 <!-- ======================================================================= -->
 247
 248 <p>Clang supports a number of builtin library functions with the same syntax as
 249 GCC, 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
 252 addition to the GCC builtins, Clang supports a number of builtins that GCC does
 253 not, which are listed here.</p>
 254
 255 <p>Please note that Clang does not and will not support all of the GCC builtins
 256 for vector operations.  Instead of using builtins, you should use the functions
 257 defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
 258 define portable wrappers for these.  Many of the Clang versions of these
 259 functions are implemented directly in terms of <a href="#vectors">extended
 260 vector support</a> instead of builtins, in order to reduce the number of
 261 builtins that we need to implement.</p>
 262
 263 <!-- ======================================================================= -->
 264 <h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
 265 <!-- ======================================================================= -->
 266
 267 <p><tt>__builtin_shufflevector</tt> is used to expression generic vector
 268 permutation/shuffle/swizzle operations. This builtin is also very important for
 269 the implementation of various target-specific header files like
 270 <tt>&lt;xmmintrin.h&gt;</tt>.
 271 </p>
 272
 273 <p><b>Syntax:</b></p>
 274
 275 <pre>
 276 __builtin_shufflevector(vec1, vec2, index1, index2, ...)
 277 </pre>
 278
 279 <p><b>Examples:</b></p>
 280
 281 <pre>
 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)
 296 </pre>
 297
 298 <p><b>Description:</b></p>
 299
 300 <p>The first two arguments to __builtin_shufflevector are vectors that have the
 301 same element type.  The remaining arguments are a list of integers that specify
 302 the elements indices of the first two vectors that should be extracted and
 303 returned in a new vector.  These element indices are numbered sequentially
 304 starting with the first vector, continuing into the second vector.  Thus, if
 305 vec1 is a 4-element vector, index 5 would refer to the second element of vec2.
 306 </p>
 307
 308 <p>The result of __builtin_shufflevector is a vector
 309 with the same element type as vec1/vec2 but that has an element count equal to
 310 the number of indices specified.
 311 </p>
 312
 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
 330 relative to the X86 GS segment register, and address space #257 causes it to be
 331 relative to the X86 FS segment.  Note that this is a very very low-level
 332 feature that should only be used if you know what you're doing (for example in
 333 an OS kernel).</p>
 334
 335 <p>Here is an example:</p>
 336
 337 <pre>
 338 #define GS_RELATIVE __attribute__((address_space(256)))
 339 int 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
 353 <!-- ======================================================================= -->
 354 <h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
 355 <!-- ======================================================================= -->
 356
 357 <p>Clang supports additional attributes that are useful for documenting program
 358 invariants and rules for static analysis tools. The extensions documented here
 359 are used by the <a
 360 href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
 361 engine</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>
 370 attribute. This attribute, which is typically affixed to a function prototype,
 371 indicates that a call to a given function never returns. Function prototypes for
 372 common functions like <tt>exit</tt> are typically annotated with this attribute,
 373 as well as a variety of common assertion handlers. Users can educate the static
 374 analyzer about their own custom assertion handles (thus cutting down on false
 375 positives due to false paths) by marking their own &quot;panic&quot; functions
 376 with this attribute.</p>
 377
 378 <p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
 379 there are special functions that for all intents and purposes should be
 380 considered panic functions (i.e., they are only called when an internal program
 381 error occurs) but may actually return so that the program can fail gracefully.
 382 The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
 383 as being interpreted as &quot;no return&quot; functions by the analyzer (thus
 384 pruning bogus paths) but will not affect compilation (as in the case of
 385 <tt>noreturn</tt>).</p>
 386
 387 <p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the
 388 same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
 389 placed at the end of function prototypes:</p>
 390
 391 <pre>
 392   void foo() <b>__attribute__((analyzer_noreturn))</b>;
 393 </pre>
 394
 395 <p>Query for this feature with __has_feature(attribute_analyzer_noreturn).</p>
 396
 397
 398 </div>
 399 </body>
 400 </html>