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