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