Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 665a8dc95379a936a26e58620c16a175d0226053 / . / docs / LanguageExtensions.html
blob: 1eeea604f6ba1bd8cf639fcbfa6c47732aaa9eab [file] [log] [blame]
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]4<html>
5<head>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]6 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
Eli Friedman0c706c22011-09-19 23:17:44 +0000[diff] [blame]7 <title>Clang Language Extensions</title>
Sean Hunt64f857b2011-06-23 01:22:53 +0000[diff] [blame]8 <link type="text/css" rel="stylesheet" href="../menu.css">
9 <link type="text/css" rel="stylesheet" href="../content.css">
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]10 <style type="text/css">
11 td {
12 vertical-align: top;
13 }
14 </style>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]15</head>
16<body>
17
18<!--#include virtual="../menu.html.incl"-->
19
20<div id="content">
21
22<h1>Clang Language Extensions</h1>
23
24<ul>
25<li><a href="#intro">Introduction</a></li>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]26<li><a href="#feature_check">Feature Checking Macros</a></li>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]27<li><a href="#has_include">Include File Checking Macros</a></li>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]28<li><a href="#builtinmacros">Builtin Macros</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]29<li><a href="#vectors">Vectors and Extended Vectors</a></li>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]30<li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li>
31<li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]32<li><a href="#checking_language_features">Checks for Standard Language Features</a>
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]33 <ul>
34 <li><a href="#cxx_exceptions">C++ exceptions</a></li>
35 <li><a href="#cxx_rtti">C++ RTTI</a></li>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]36 </ul></li>
37<li><a href="#checking_upcoming_features">Checks for Upcoming Standard Language Features</a>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]38 <ul>
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]39 <li><a href="#cxx0x">C++11</a>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]40 <ul>
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]41 <li><a href="#cxx_access_control_sfinae">C++11 SFINAE includes
42 access control</a></li>
43 <li><a href="#cxx_alias_templates">C++11 alias templates</a></li>
44 <li><a href="#cxx_alignas">C++11 alignment specifiers</a></li>
45 <li><a href="#cxx_attributes">C++11 attributes</a></li>
46 <li><a href="#cxx_constexpr">C++11 generalized constant expressions</a></li>
47 <li><a href="#cxx_decltype">C++11 <tt>decltype()</tt></a></li>
48 <li><a href="#cxx_default_function_template_args">C++11 default template arguments in function templates</a></li>
Douglas Gregorf695a692011-11-01 01:19:34 +0000[diff] [blame]49 <li><a href="#cxx_defaulted_functions">C++11 defaulted functions</a></li>
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]50 <li><a href="#cxx_delegating_constructor">C++11 delegating constructors</a></li>
51 <li><a href="#cxx_deleted_functions">C++11 deleted functions</a></li>
52 <li><a href="#cxx_explicit_conversions">C++11 explicit conversion functions</a></li>
53 <li><a href="#cxx_generalized_initializers">C++11 generalized initializers</a></li>
54 <li><a href="#cxx_implicit_moves">C++11 implicit move constructors/assignment operators</a></li>
55 <li><a href="#cxx_inheriting_constructors">C++11 inheriting constructors</a></li>
56 <li><a href="#cxx_inline_namespaces">C++11 inline namespaces</a></li>
57 <li><a href="#cxx_lambdas">C++11 lambdas</a></li>
58 <li><a href="#cxx_noexcept">C++11 noexcept specification</a></li>
59 <li><a href="#cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</a></li>
60 <li><a href="#cxx_nullptr">C++11 nullptr</a></li>
61 <li><a href="#cxx_override_control">C++11 override control</a></li>
62 <li><a href="#cxx_range_for">C++11 range-based for loop</a></li>
63 <li><a href="#cxx_raw_string_literals">C++11 raw string literals</a></li>
64 <li><a href="#cxx_rvalue_references">C++11 rvalue references</a></li>
65 <li><a href="#cxx_reference_qualified_functions">C++11 reference-qualified functions</a></li>
66 <li><a href="#cxx_static_assert">C++11 <tt>static_assert()</tt></a></li>
67 <li><a href="#cxx_auto_type">C++11 type inference</a></li>
68 <li><a href="#cxx_strong_enums">C++11 strongly-typed enumerations</a></li>
69 <li><a href="#cxx_trailing_return">C++11 trailing return type</a></li>
70 <li><a href="#cxx_unicode_literals">C++11 Unicode string literals</a></li>
71 <li><a href="#cxx_unrestricted_unions">C++11 unrestricted unions</a></li>
72 <li><a href="#cxx_user_literals">C++11 user-defined literals</a></li>
73 <li><a href="#cxx_variadic_templates">C++11 variadic templates</a></li>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]74 </ul></li>
Benjamin Kramerffbe9b92011-12-23 17:00:35 +0000[diff] [blame]75 <li><a href="#c11">C11</a>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]76 <ul>
Benjamin Kramerffbe9b92011-12-23 17:00:35 +0000[diff] [blame]77 <li><a href="#c_alignas">C11 alignment specifiers</a></li>
78 <li><a href="#c_generic_selections">C11 generic selections</a></li>
79 <li><a href="#c_static_assert">C11 <tt>_Static_assert()</tt></a></li>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]80 </ul></li>
81 </ul> </li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]82<li><a href="#checking_type_traits">Checks for Type Traits</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]83<li><a href="#blocks">Blocks</a></li>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]84<li><a href="#objc_features">Objective-C Features</a>
85 <ul>
86 <li><a href="#objc_instancetype">Related result types</a></li>
John McCallf85e1932011-06-15 23:02:42 +0000[diff] [blame]87 <li><a href="#objc_arc">Automatic reference counting</a></li>
Douglas Gregor5471bc82011-09-08 17:18:35 +0000[diff] [blame]88 <li><a href="#objc_fixed_enum">Enumerations with a fixed underlying type</a></li>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]89 </ul>
90</li>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]91<li><a href="#overloading-in-c">Function Overloading in C</a></li>
Eli Friedman0c706c22011-09-19 23:17:44 +0000[diff] [blame]92<li><a href="#complex-list-init">Initializer lists for complex numbers in C</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]93<li><a href="#builtins">Builtin Functions</a>
94 <ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]95 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]96 <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li>
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]97 <li><a href="#__sync_swap">__sync_swap</a></li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]98 </ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]99</li>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]100<li><a href="#targetspecific">Target-Specific Extensions</a>
101 <ul>
102 <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li>
103 </ul>
104</li>
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]105<li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li>
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame^]106<li><a href="#dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</a>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]107 <ul>
108 <li><a href="#address_sanitizer">AddressSanitizer</a></li>
109 </ul>
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame^]110</li>
111<li><a href="#threadsafety">Thread Safety Annotation Checking</a>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]112 <ul>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]113 <li><a href="#ts_noanal"><tt>no_thread_safety_analysis</tt></a></li>
114 <li><a href="#ts_lockable"><tt>lockable</tt></a></li>
115 <li><a href="#ts_scopedlockable"><tt>scoped_lockable</tt></a></li>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]116 <li><a href="#ts_guardedvar"><tt>guarded_var</tt></a></li>
117 <li><a href="#ts_ptguardedvar"><tt>pt_guarded_var</tt></a></li>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]118 <li><a href="#ts_guardedby"><tt>guarded_by(l)</tt></a></li>
119 <li><a href="#ts_ptguardedby"><tt>pt_guarded_by(l)</tt></a></li>
120 <li><a href="#ts_acquiredbefore"><tt>acquired_before(...)</tt></a></li>
121 <li><a href="#ts_acquiredafter"><tt>acquired_after(...)</tt></a></li>
122 <li><a href="#ts_elf"><tt>exclusive_lock_function(...)</tt></a></li>
123 <li><a href="#ts_slf"><tt>shared_lock_function(...)</tt></a></li>
124 <li><a href="#ts_etf"><tt>exclusive_trylock_function(...)</tt></a></li>
125 <li><a href="#ts_stf"><tt>shared_trylock_function(...)</tt></a></li>
126 <li><a href="#ts_uf"><tt>unlock_function(...)</tt></a></li>
127 <li><a href="#ts_lr"><tt>lock_returned(l)</tt></a></li>
128 <li><a href="#ts_le"><tt>locks_excluded(...)</tt></a></li>
129 <li><a href="#ts_elr"><tt>exclusive_locks_required(...)</tt></a></li>
130 <li><a href="#ts_slr"><tt>shared_locks_required(...)</tt></a></li>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]131 </ul>
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame^]132</li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]133</ul>
134
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]135<!-- ======================================================================= -->
136<h2 id="intro">Introduction</h2>
137<!-- ======================================================================= -->
138
139<p>This document describes the language extensions provided by Clang. In
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]140addition to the language extensions listed here, Clang aims to support a broad
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]141range of GCC extensions. Please see the <a
142href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
143more information on these extensions.</p>
144
145<!-- ======================================================================= -->
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]146<h2 id="feature_check">Feature Checking Macros</h2>
147<!-- ======================================================================= -->
148
149<p>Language extensions can be very useful, but only if you know you can depend
Chris Lattnerc70e1932011-03-21 16:25:11 +0000[diff] [blame]150on them. In order to allow fine-grain features checks, we support three builtin
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]151function-like macros. This allows you to directly test for a feature in your
152code without having to resort to something like autoconf or fragile "compiler
153version checks".</p>
154
155<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]156<h3><a name="__has_builtin">__has_builtin</a></h3>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]157<!-- ======================================================================= -->
158
159<p>This function-like macro takes a single identifier argument that is the name
160of a builtin function. It evaluates to 1 if the builtin is supported or 0 if
161not. It can be used like this:</p>
162
163<blockquote>
164<pre>
165#ifndef __has_builtin // Optional of course.
166 #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
167#endif
168
169...
170#if __has_builtin(__builtin_trap)
171 __builtin_trap();
172#else
173 abort();
174#endif
175...
176</pre>
177</blockquote>
178
179
180<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]181<h3><a name="__has_feature_extension"> __has_feature and __has_extension</a></h3>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]182<!-- ======================================================================= -->
183
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]184<p>These function-like macros take a single identifier argument that is the
185name of a feature. <code>__has_feature</code> evaluates to 1 if the feature
186is both supported by Clang and standardized in the current language standard
187or 0 if not (but see <a href="#has_feature_back_compat">below</a>), while
188<code>__has_extension</code> evaluates to 1 if the feature is supported by
189Clang in the current language (either as a language extension or a standard
190language feature) or 0 if not. They can be used like this:</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]191
192<blockquote>
193<pre>
194#ifndef __has_feature // Optional of course.
195 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
196#endif
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]197#ifndef __has_extension
198 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
199#endif
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]200
201...
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]202#if __has_feature(cxx_rvalue_references)
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]203// This code will only be compiled with the -std=c++11 and -std=gnu++11
204// options, because rvalue references are only standardized in C++11.
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]205#endif
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]206
207#if __has_extension(cxx_rvalue_references)
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]208// This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]209// and -std=gnu++98 options, because rvalue references are supported as a
210// language extension in C++98.
211#endif
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]212</pre>
213</blockquote>
214
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]215<p id="has_feature_back_compat">For backwards compatibility reasons,
216<code>__has_feature</code> can also be used to test for support for
217non-standardized features, i.e. features not prefixed <code>c_</code>,
218<code>cxx_</code> or <code>objc_</code>.</p>
219
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]220<p id="has_feature_for_non_language_features">
221Another use of <code>__has_feature</code> is to check for compiler features
222not related to the language standard, such as e.g.
223<a href="AddressSanitizer.html">AddressSanitizer</a>.
224
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]225<p>If the <code>-pedantic-errors</code> option is given,
226<code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p>
227
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]228<p>The feature tag is described along with the language feature below.</p>
229
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]230<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]231<h3><a name="__has_attribute">__has_attribute</a></h3>
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]232<!-- ======================================================================= -->
233
234<p>This function-like macro takes a single identifier argument that is the name
235of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It
236can be used like this:</p>
237
238<blockquote>
239<pre>
240#ifndef __has_attribute // Optional of course.
241 #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
242#endif
243
244...
Anders Carlsson961003d2011-01-24 03:54:51 +0000[diff] [blame]245#if __has_attribute(always_inline)
246#define ALWAYS_INLINE __attribute__((always_inline))
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]247#else
Anders Carlsson961003d2011-01-24 03:54:51 +0000[diff] [blame]248#define ALWAYS_INLINE
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]249#endif
250...
251</pre>
252</blockquote>
253
254<!-- ======================================================================= -->
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]255<h2 id="has_include">Include File Checking Macros</h2>
256<!-- ======================================================================= -->
257
258<p>Not all developments systems have the same include files.
259The <a href="#__has_include">__has_include</a> and
260<a href="#__has_include_next">__has_include_next</a> macros allow you to
261check for the existence of an include file before doing
262a possibly failing #include directive.</p>
263
264<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]265<h3><a name="__has_include">__has_include</a></h3>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]266<!-- ======================================================================= -->
267
268<p>This function-like macro takes a single file name string argument that
269is the name of an include file. It evaluates to 1 if the file can
270be found using the include paths, or 0 otherwise:</p>
271
272<blockquote>
273<pre>
274// Note the two possible file name string formats.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]275#if __has_include("myinclude.h") &amp;&amp; __has_include(&lt;stdint.h&gt;)
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]276# include "myinclude.h"
277#endif
278
279// To avoid problem with non-clang compilers not having this macro.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]280#if defined(__has_include) &amp;&amp; __has_include("myinclude.h")
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]281# include "myinclude.h"
282#endif
283</pre>
284</blockquote>
285
286<p>To test for this feature, use #if defined(__has_include).</p>
287
288<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]289<h3><a name="__has_include_next">__has_include_next</a></h3>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]290<!-- ======================================================================= -->
291
292<p>This function-like macro takes a single file name string argument that
293is the name of an include file. It is like __has_include except that it
294looks for the second instance of the given file found in the include
295paths. It evaluates to 1 if the second instance of the file can
296be found using the include paths, or 0 otherwise:</p>
297
298<blockquote>
299<pre>
300// Note the two possible file name string formats.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]301#if __has_include_next("myinclude.h") &amp;&amp; __has_include_next(&lt;stdint.h&gt;)
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]302# include_next "myinclude.h"
303#endif
304
305// To avoid problem with non-clang compilers not having this macro.
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]306#if defined(__has_include_next) &amp;&amp; __has_include_next("myinclude.h")
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]307# include_next "myinclude.h"
308#endif
309</pre>
310</blockquote>
311
312<p>Note that __has_include_next, like the GNU extension
313#include_next directive, is intended for use in headers only,
314and will issue a warning if used in the top-level compilation
315file. A warning will also be issued if an absolute path
316is used in the file argument.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]317
Ted Kremenekd7681502011-10-12 19:46:30 +0000[diff] [blame]318
319<!-- ======================================================================= -->
320<h3><a name="__has_warning">__has_warning</a></h3>
321<!-- ======================================================================= -->
322
323<p>This function-like macro takes a string literal that represents a command
324 line option for a warning and returns true if that is a valid warning
325 option.</p>
326
327<blockquote>
328<pre>
329#if __has_warning("-Wformat")
330...
331#endif
332</pre>
333</blockquote>
334
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]335<!-- ======================================================================= -->
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]336<h2 id="builtinmacros">Builtin Macros</h2>
337<!-- ======================================================================= -->
338
Douglas Gregor4290fbd2010-04-30 02:51:06 +0000[diff] [blame]339<dl>
340 <dt><code>__BASE_FILE__</code></dt>
341 <dd>Defined to a string that contains the name of the main input
342 file passed to Clang.</dd>
343
344 <dt><code>__COUNTER__</code></dt>
345 <dd>Defined to an integer value that starts at zero and is
346 incremented each time the <code>__COUNTER__</code> macro is
347 expanded.</dd>
348
349 <dt><code>__INCLUDE_LEVEL__</code></dt>
350 <dd>Defined to an integral value that is the include depth of the
351 file currently being translated. For the main file, this value is
352 zero.</dd>
353
354 <dt><code>__TIMESTAMP__</code></dt>
355 <dd>Defined to the date and time of the last modification of the
356 current source file.</dd>
357
358 <dt><code>__clang__</code></dt>
359 <dd>Defined when compiling with Clang</dd>
360
361 <dt><code>__clang_major__</code></dt>
Chris Lattnerd4b66b92011-12-15 19:06:36 +0000[diff] [blame]362 <dd>Defined to the major marketing version number of Clang (e.g., the
363 2 in 2.0.1). Note that marketing version numbers should not be used to
364 check for language features, as different vendors use different numbering
365 schemes. Instead, use the <a href="#feature_check">feature checking
366 macros</a>.</dd>
Douglas Gregor4290fbd2010-04-30 02:51:06 +0000[diff] [blame]367
368 <dt><code>__clang_minor__</code></dt>
369 <dd>Defined to the minor version number of Clang (e.g., the 0 in
Chris Lattnerd4b66b92011-12-15 19:06:36 +0000[diff] [blame]370 2.0.1). Note that marketing version numbers should not be used to
371 check for language features, as different vendors use different numbering
372 schemes. Instead, use the <a href="#feature_check">feature checking
373 macros</a>.</dd>
Douglas Gregor4290fbd2010-04-30 02:51:06 +0000[diff] [blame]374
375 <dt><code>__clang_patchlevel__</code></dt>
Chris Lattnerd4b66b92011-12-15 19:06:36 +0000[diff] [blame]376 <dd>Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).</dd>
Douglas Gregor4290fbd2010-04-30 02:51:06 +0000[diff] [blame]377
378 <dt><code>__clang_version__</code></dt>
Chris Lattnerd4b66b92011-12-15 19:06:36 +0000[diff] [blame]379 <dd>Defined to a string that captures the Clang marketing version, including
380 the Subversion tag or revision number, e.g., "1.5 (trunk 102332)".</dd>
Douglas Gregor4290fbd2010-04-30 02:51:06 +0000[diff] [blame]381</dl>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]382
383<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]384<h2 id="vectors">Vectors and Extended Vectors</h2>
385<!-- ======================================================================= -->
386
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]387<p>Supports the GCC vector extensions, plus some stuff like V[1].</p>
388
389<p>Also supports <tt>ext_vector</tt>, which additionally support for V.xyzw
390syntax and other tidbits as seen in OpenCL. An example is:</p>
391
392<blockquote>
393<pre>
394typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>;
395typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>;
396
397float4 foo(float2 a, float2 b) {
398 float4 c;
399 c.xz = a;
400 c.yw = b;
401 return c;
402}
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]403</pre>
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]404</blockquote>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]405
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]406<p>Query for this feature with __has_extension(attribute_ext_vector_type).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]407
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]408<p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
409
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]410<!-- ======================================================================= -->
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]411<h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]412<!-- ======================================================================= -->
413
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]414<p>An optional string message can be added to the <tt>deprecated</tt>
415and <tt>unavailable</tt> attributes. For example:</p>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]416
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]417<blockquote>
Chris Lattner4836d6a2010-11-09 19:43:35 +0000[diff] [blame]418<pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]419</blockquote>
420
421<p>If the deprecated or unavailable declaration is used, the message
422will be incorporated into the appropriate diagnostic:</p>
423
424<blockquote>
Chris Lattner4836d6a2010-11-09 19:43:35 +0000[diff] [blame]425<pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! [-Wdeprecated-declarations]
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]426 explode();
427 ^</pre>
428</blockquote>
429
430<p>Query for this feature
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]431with <tt>__has_extension(attribute_deprecated_with_message)</tt>
432and <tt>__has_extension(attribute_unavailable_with_message)</tt>.</p>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]433
434<!-- ======================================================================= -->
435<h2 id="attributes-on-enumerators">Attributes on Enumerators</h2>
436<!-- ======================================================================= -->
437
438<p>Clang allows attributes to be written on individual enumerators.
439This allows enumerators to be deprecated, made unavailable, etc. The
440attribute must appear after the enumerator name and before any
441initializer, like so:</p>
442
443<blockquote>
444<pre>enum OperationMode {
445 OM_Invalid,
446 OM_Normal,
447 OM_Terrified __attribute__((deprecated)),
448 OM_AbortOnError __attribute__((deprecated)) = 4
449};</pre>
450</blockquote>
451
452<p>Attributes on the <tt>enum</tt> declaration do not apply to
453individual enumerators.</p>
454
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]455<p>Query for this feature with <tt>__has_extension(enumerator_attributes)</tt>.</p>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]456
457<!-- ======================================================================= -->
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]458<h2 id="checking_language_features">Checks for Standard Language Features</h2>
459<!-- ======================================================================= -->
460
461<p>The <tt>__has_feature</tt> macro can be used to query if certain standard language features are
462enabled. Those features are listed here.</p>
463
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]464<h3 id="cxx_exceptions">C++ exceptions</h3>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]465
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]466<p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For
Sean Hunt647ba1b2011-06-23 00:42:53 +0000[diff] [blame]467example, compiling code with <tt>-fexceptions</tt> enables C++ exceptions.</p>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]468
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]469<h3 id="cxx_rtti">C++ RTTI</h3>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]470
Ted Kremenek0eb95602009-12-03 02:06:43 +0000[diff] [blame]471<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]472compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]473
474<!-- ======================================================================= -->
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]475<h2 id="checking_upcoming_features">Checks for Upcoming Standard Language Features</h2>
476<!-- ======================================================================= -->
477
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]478<p>The <tt>__has_feature</tt> or <tt>__has_extension</tt> macros can be used
479to query if certain upcoming standard language features are enabled. Those
480features are listed here. Features that are not yet implemented will be
481noted.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]482
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]483<h3 id="cxx0x">C++11</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]484
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]485<p>The features listed below are slated for inclusion in the upcoming
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]486C++11 standard. As a result, all these features are enabled
487with the <tt>-std=c++11</tt> option when compiling C++ code.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]488
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]489<h4 id="cxx_access_control_sfinae">C++11 SFINAE includes access control</h4>
Douglas Gregor7822ee32011-05-11 23:45:11 +0000[diff] [blame]490
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]491<p>Use <tt>__has_feature(cxx_access_control_sfinae)</tt> or <tt>__has_extension(cxx_access_control_sfinae)</tt> to determine whether access-control errors (e.g., calling a private constructor) are considered to be template argument deduction errors (aka SFINAE errors), per <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170">C++ DR1170</a>.</p>
Douglas Gregor7822ee32011-05-11 23:45:11 +0000[diff] [blame]492
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]493<h4 id="cxx_alias_templates">C++11 alias templates</h4>
Richard Smith3e4c6c42011-05-05 21:57:07 +0000[diff] [blame]494
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]495<p>Use <tt>__has_feature(cxx_alias_templates)</tt> or
496<tt>__has_extension(cxx_alias_templates)</tt> to determine if support for
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]497C++11's alias declarations and alias templates is enabled.</p>
Richard Smith3e4c6c42011-05-05 21:57:07 +0000[diff] [blame]498
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]499<h4 id="cxx_alignas">C++11 alignment specifiers</h4>
Peter Collingbournefd5f6862011-10-14 23:44:46 +0000[diff] [blame]500
501<p>Use <tt>__has_feature(cxx_alignas)</tt> or
502<tt>__has_extension(cxx_alignas)</tt> to determine if support for alignment
503specifiers using <tt>alignas</tt> is enabled.</p>
504
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]505<h4 id="cxx_attributes">C++11 attributes</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]506
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]507<p>Use <tt>__has_feature(cxx_attributes)</tt> or
508<tt>__has_extension(cxx_attributes)</tt> to determine if support for attribute
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]509parsing with C++11's square bracket notation is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]510
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]511<h4 id="cxx_constexpr">C++11 generalized constant expressions</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]512
513<p>Use <tt>__has_feature(cxx_constexpr)</tt> to determine if support
514for generalized constant expressions (e.g., <tt>constexpr</tt>) is
515enabled. Clang does not currently implement this feature.</p>
516
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]517<h4 id="cxx_decltype">C++11 <tt>decltype()</tt></h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]518
519<p>Use <tt>__has_feature(cxx_decltype)</tt> or
520<tt>__has_extension(cxx_decltype)</tt> to determine if support for the
521<tt>decltype()</tt> specifier is enabled.</p>
522
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]523<h4 id="cxx_default_function_template_args">C++11 default template arguments in function templates</h4>
Douglas Gregor07508002011-02-05 20:35:30 +0000[diff] [blame]524
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]525<p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or
526<tt>__has_extension(cxx_default_function_template_args)</tt> to determine
527if support for default template arguments in function templates is enabled.</p>
Douglas Gregor07508002011-02-05 20:35:30 +0000[diff] [blame]528
Douglas Gregorf695a692011-11-01 01:19:34 +0000[diff] [blame]529<h4 id="cxx_defaulted_functions">C++11 <tt>default</tt>ed functions</h4>
530
531<p>Use <tt>__has_feature(cxx_defaulted_functions)</tt> or
532<tt>__has_extension(cxx_defaulted_functions)</tt> to determine if support for
533defaulted function definitions (with <tt>= default</tt>) is enabled.</p>
534
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]535<h4 id="cxx_delegating_constructors">C++11 delegating constructors</h4>
Sean Huntd9624992011-06-23 06:11:37 +0000[diff] [blame]536
537<p>Use <tt>__has_feature(cxx_delegating_constructors)</tt> to determine if
538support for delegating constructors is enabled.</p>
539
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]540<h4 id="cxx_deleted_functions">C++11 <tt>delete</tt>d functions</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]541
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]542<p>Use <tt>__has_feature(cxx_deleted_functions)</tt> or
543<tt>__has_extension(cxx_deleted_functions)</tt> to determine if support for
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]544deleted function definitions (with <tt>= delete</tt>) is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]545
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame^]546<h4 id="cxx_explicit_conversions">C++11 explicit conversion functions</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]547<p>Use <tt>__has_feature(cxx_explicit_conversions)</tt> to determine if support for <tt>explicit</tt> conversion functions is enabled.</p>
548
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]549<h4 id="cxx_generalized_initializers">C++11 generalized initializers</h4>
Sean Hunte1f6dea2011-08-07 00:34:32 +0000[diff] [blame]550
551<p>Use <tt>__has_feature(cxx_generalized_initializers)</tt> to determine if
552support for generalized initializers (using braced lists and
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]553<tt>std::initializer_list</tt>) is enabled. Clang does not currently implement
554this feature.</p>
555
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]556<h4 id="cxx_implicit_moves">C++11 implicit move constructors/assignment operators</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]557
Sebastian Redl72a81d22011-10-10 18:10:00 +0000[diff] [blame]558<p>Use <tt>__has_feature(cxx_implicit_moves)</tt> to determine if Clang will
559implicitly generate move constructors and move assignment operators where needed.</p>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]560
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]561<h4 id="cxx_inheriting_constructors">C++11 inheriting constructors</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]562
563<p>Use <tt>__has_feature(cxx_inheriting_constructors)</tt> to determine if support for inheriting constructors is enabled. Clang does not currently implement this feature.</p>
564
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]565<h4 id="cxx_inline_namespaces">C++11 inline namespaces</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]566
567<p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> or
568<tt>__has_extension(cxx_inline_namespaces)</tt> to determine if support for
569inline namespaces is enabled.</p>
Sean Hunte1f6dea2011-08-07 00:34:32 +0000[diff] [blame]570
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]571<h4 id="cxx_lambdas">C++11 lambdas</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]572
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]573<p>Use <tt>__has_feature(cxx_lambdas)</tt> or
574<tt>__has_extension(cxx_lambdas)</tt> to determine if support for lambdas
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]575is enabled. Clang does not currently implement this feature.</p>
576
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]577<h4 id="cxx_noexcept">C++11 noexcept</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]578
579<p>Use <tt>__has_feature(cxx_noexcept)</tt> or
580<tt>__has_extension(cxx_noexcept)</tt> to determine if support for noexcept
581exception specifications is enabled.</p>
582
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]583<h4 id="cxx_nonstatic_member_init">C++11 in-class non-static data member initialization</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]584
585<p>Use <tt>__has_feature(cxx_nonstatic_member_init)</tt> to determine whether in-class initialization of non-static data members is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]586
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]587<h4 id="cxx_nullptr">C++11 <tt>nullptr</tt></h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]588
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]589<p>Use <tt>__has_feature(cxx_nullptr)</tt> or
590<tt>__has_extension(cxx_nullptr)</tt> to determine if support for
Douglas Gregor84ee2ee2011-05-21 23:15:46 +0000[diff] [blame]591<tt>nullptr</tt> is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]592
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]593<h4 id="cxx_override_control">C++11 <tt>override control</tt></h4>
Anders Carlssonc8b9f792011-03-25 15:04:23 +0000[diff] [blame]594
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]595<p>Use <tt>__has_feature(cxx_override_control)</tt> or
596<tt>__has_extension(cxx_override_control)</tt> to determine if support for
Anders Carlssonc8b9f792011-03-25 15:04:23 +0000[diff] [blame]597the override control keywords is enabled.</p>
598
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]599<h4 id="cxx_reference_qualified_functions">C++11 reference-qualified functions</h4>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]600<p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> or
601<tt>__has_extension(cxx_reference_qualified_functions)</tt> to determine
602if support for reference-qualified functions (e.g., member functions with
603<code>&amp;</code> or <code>&amp;&amp;</code> applied to <code>*this</code>)
604is enabled.</p>
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]605
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]606<h4 id="cxx_range_for">C++11 range-based <tt>for</tt> loop</h4>
Richard Smitha391a462011-04-15 15:14:40 +0000[diff] [blame]607
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]608<p>Use <tt>__has_feature(cxx_range_for)</tt> or
609<tt>__has_extension(cxx_range_for)</tt> to determine if support for the
610range-based for loop is enabled. </p>
Richard Smitha391a462011-04-15 15:14:40 +0000[diff] [blame]611
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]612<h4 id="cxx_raw_string_literals">C++11 raw string literals</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]613<p>Use <tt>__has_feature(cxx_raw_string_literals)</tt> to determine if support for raw string literals (e.g., <tt>R"foo\bar"</tt>) is enabled.</p>
614
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]615<h4 id="cxx_rvalue_references">C++11 rvalue references</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]616
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]617<p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or
618<tt>__has_extension(cxx_rvalue_references)</tt> to determine if support for
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]619rvalue references is enabled. </p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]620
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]621<h4 id="cxx_static_assert">C++11 <tt>static_assert()</tt></h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]622
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]623<p>Use <tt>__has_feature(cxx_static_assert)</tt> or
624<tt>__has_extension(cxx_static_assert)</tt> to determine if support for
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]625compile-time assertions using <tt>static_assert</tt> is enabled.</p>
626
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]627<h4 id="cxx_auto_type">C++11 type inference</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]628
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]629<p>Use <tt>__has_feature(cxx_auto_type)</tt> or
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]630<tt>__has_extension(cxx_auto_type)</tt> to determine C++11 type inference is
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]631supported using the <tt>auto</tt> specifier. If this is disabled, <tt>auto</tt>
632will instead be a storage class specifier, as in C or C++98.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]633
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]634<h4 id="cxx_strong_enums">C++11 strongly typed enumerations</h4>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]635
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]636<p>Use <tt>__has_feature(cxx_strong_enums)</tt> or
637<tt>__has_extension(cxx_strong_enums)</tt> to determine if support for
638strongly typed, scoped enumerations is enabled.</p>
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]639
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]640<h4 id="cxx_trailing_return">C++11 trailing return type</h4>
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]641
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]642<p>Use <tt>__has_feature(cxx_trailing_return)</tt> or
643<tt>__has_extension(cxx_trailing_return)</tt> to determine if support for the
644alternate function declaration syntax with trailing return type is enabled.</p>
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]645
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]646<h4 id="cxx_unicode_literals">C++11 Unicode string literals</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]647<p>Use <tt>__has_feature(cxx_unicode_literals)</tt> to determine if
648support for Unicode string literals is enabled.</p>
Sebastian Redl4561ecd2011-03-15 21:17:12 +0000[diff] [blame]649
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]650<h4 id="cxx_unrestricted_unions">C++11 unrestricted unions</h4>
Sebastian Redl4561ecd2011-03-15 21:17:12 +0000[diff] [blame]651
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]652<p>Use <tt>__has_feature(cxx_unrestricted_unions)</tt> to determine if support for unrestricted unions is enabled. Clang does not currently support this feature.</p>
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]653
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]654<h4 id="cxx_user_literals">C++11 user-defined literals</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]655
656<p>Use <tt>__has_feature(cxx_user_literals)</tt> to determine if support for user-defined literals is enabled. Clang does not currently support this feature.</p>
657
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]658<h4 id="cxx_variadic_templates">C++11 variadic templates</h4>
Douglas Gregorece38942011-08-29 17:28:38 +0000[diff] [blame]659
660<p>Use <tt>__has_feature(cxx_variadic_templates)</tt> or
661<tt>__has_extension(cxx_variadic_templates)</tt> to determine if support
662for variadic templates is enabled.</p>
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]663
Benjamin Kramerffbe9b92011-12-23 17:00:35 +0000[diff] [blame]664<h3 id="c11">C11</h3>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]665
666<p>The features listed below are slated for inclusion in the upcoming
Benjamin Kramerffbe9b92011-12-23 17:00:35 +0000[diff] [blame]667C11 standard. As a result, all these features are enabled
668with the <tt>-std=c11</tt> option when compiling C code.</p>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]669
Benjamin Kramerffbe9b92011-12-23 17:00:35 +0000[diff] [blame]670<h4 id="c_alignas">C11 alignment specifiers</h4>
Peter Collingbournefd5f6862011-10-14 23:44:46 +0000[diff] [blame]671
672<p>Use <tt>__has_feature(c_alignas)</tt> or <tt>__has_extension(c_alignas)</tt>
673to determine if support for alignment specifiers using <tt>_Alignas</tt>
674is enabled.</p>
675
Benjamin Kramerffbe9b92011-12-23 17:00:35 +0000[diff] [blame]676<h4 id="c_generic_selections">C11 generic selections</h4>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]677
678<p>Use <tt>__has_feature(c_generic_selections)</tt> or
679<tt>__has_extension(c_generic_selections)</tt> to determine if support for
680generic selections is enabled.</p>
681
Benjamin Kramerffbe9b92011-12-23 17:00:35 +0000[diff] [blame]682<p>As an extension, the C11 generic selection expression is available in all
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]683languages supported by Clang. The syntax is the same as that given in the
Benjamin Kramerffbe9b92011-12-23 17:00:35 +0000[diff] [blame]684C11 standard.</p>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]685
686<p>In C, type compatibility is decided according to the rules given in the
687appropriate standard, but in C++, which lacks the type compatibility rules
688used in C, types are considered compatible only if they are equivalent.</p>
689
Benjamin Kramerffbe9b92011-12-23 17:00:35 +0000[diff] [blame]690<h4 id="c_static_assert">C11 <tt>_Static_assert()</tt></h4>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]691
692<p>Use <tt>__has_feature(c_static_assert)</tt> or
693<tt>__has_extension(c_static_assert)</tt> to determine if support for
694compile-time assertions using <tt>_Static_assert</tt> is enabled.</p>
695
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]696<!-- ======================================================================= -->
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]697<h2 id="checking_type_traits">Checks for Type Traits</h2>
698<!-- ======================================================================= -->
699
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]700<p>Clang supports the <a href="http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html">GNU C++ type traits</a> and a subset of the <a href="http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx">Microsoft Visual C++ Type traits</a>. For each supported type trait <code>__X</code>, <code>__has_extension(X)</code> indicates the presence of the type trait. For example:
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]701<blockquote>
702<pre>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]703#if __has_extension(is_convertible_to)
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]704template&lt;typename From, typename To&gt;
705struct is_convertible_to {
706 static const bool value = __is_convertible_to(From, To);
707};
708#else
709// Emulate type trait
710#endif
711</pre>
712</blockquote>
713
714<p>The following type traits are supported by Clang:</p>
715<ul>
716 <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li>
717 <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li>
718 <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li>
719 <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li>
720 <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li>
721 <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li>
722 <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li>
723 <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li>
724 <li><code>__is_abstract</code> (GNU, Microsoft)</li>
725 <li><code>__is_base_of</code> (GNU, Microsoft)</li>
726 <li><code>__is_class</code> (GNU, Microsoft)</li>
727 <li><code>__is_convertible_to</code> (Microsoft)</li>
728 <li><code>__is_empty</code> (GNU, Microsoft)</li>
729 <li><code>__is_enum</code> (GNU, Microsoft)</li>
730 <li><code>__is_pod</code> (GNU, Microsoft)</li>
731 <li><code>__is_polymorphic</code> (GNU, Microsoft)</li>
732 <li><code>__is_union</code> (GNU, Microsoft)</li>
733 <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li>
Douglas Gregor5e9392b2011-12-03 18:14:24 +0000[diff] [blame]734 <li><code>__is_final</code>: Determines whether the given type is declared with a <code>final</code> class-virt-specifier.</li>
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]735 <li><code>__underlying_type(type)</code>: Retrieves the underlying type for a given <code>enum</code> type. This trait is required to implement the C++11 standard library.</li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]736</ul>
737
738<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]739<h2 id="blocks">Blocks</h2>
740<!-- ======================================================================= -->
741
Chris Lattnera7dbdf52009-03-09 07:03:22 +0000[diff] [blame]742<p>The syntax and high level language feature description is in <a
743href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
744details for the clang implementation are in <a
Chris Lattner5d7650b2010-03-16 21:43:03 +0000[diff] [blame]745href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]746
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]747
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]748<p>Query for this feature with __has_extension(blocks).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]749
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]750<!-- ======================================================================= -->
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]751<h2 id="objc_features">Objective-C Features</h2>
752<!-- ======================================================================= -->
753
754<h3 id="objc_instancetype">Related result types</h3>
755
756<p>According to Cocoa conventions, Objective-C methods with certain names ("init", "alloc", etc.) always return objects that are an instance of the receiving class's type. Such methods are said to have a "related result type", meaning that a message send to one of these methods will have the same static type as an instance of the receiver class. For example, given the following classes:</p>
757
758<blockquote>
759<pre>
760@interface NSObject
761+ (id)alloc;
762- (id)init;
763@end
764
765@interface NSArray : NSObject
766@end
767</pre>
768</blockquote>
769
770<p>and this common initialization pattern</p>
771
772<blockquote>
773<pre>
774NSArray *array = [[NSArray alloc] init];
775</pre>
776</blockquote>
777
778<p>the type of the expression <code>[NSArray alloc]</code> is
779<code>NSArray*</code> because <code>alloc</code> implicitly has a
780related result type. Similarly, the type of the expression
781<code>[[NSArray alloc] init]</code> is <code>NSArray*</code>, since
782<code>init</code> has a related result type and its receiver is known
783to have the type <code>NSArray *</code>. If neither <code>alloc</code> nor <code>init</code> had a related result type, the expressions would have had type <code>id</code>, as declared in the method signature.</p>
784
Douglas Gregore97179c2011-09-08 01:46:34 +0000[diff] [blame]785<p>A method with a related result type can be declared by using the
786type <tt>instancetype</tt> as its result type. <tt>instancetype</tt>
787is a contextual keyword that is only permitted in the result type of
788an Objective-C method, e.g.</p>
789
790<pre>
791@interface A
792+ (<b>instancetype</b>)constructAnA;
793@end
794</pre>
795
796<p>The related result type can also be inferred for some methods.
797To determine whether a method has an inferred related result type, the first
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]798word in the camel-case selector (e.g., "init" in "initWithObjects") is
Douglas Gregor8a0ace62011-11-03 18:33:01 +0000[diff] [blame]799considered, and the method will have a related result type if its return
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]800type is compatible with the type of its class and if</p>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]801
802<ul>
803
804 <li>the first word is "alloc" or "new", and the method is a class
805 method, or</li>
806
807 <li>the first word is "autorelease", "init", "retain", or "self",
808 and the method is an instance method.</li>
809
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]810</ul>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]811
812<p>If a method with a related result type is overridden by a subclass
813method, the subclass method must also return a type that is compatible
814with the subclass type. For example:</p>
815
816<blockquote>
817<pre>
818@interface NSString : NSObject
819- (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
820@end
821</pre>
822</blockquote>
823
824<p>Related result types only affect the type of a message send or
825property access via the given method. In all other respects, a method
Douglas Gregore97179c2011-09-08 01:46:34 +0000[diff] [blame]826with a related result type is treated the same way as method that
827returns <tt>id</tt>.</p>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]828
Douglas Gregoraebb6532011-09-08 17:19:31 +0000[diff] [blame]829<p>Use <tt>__has_feature(objc_instancetype)</tt> to determine whether
830the <tt>instancetype</tt> contextual keyword is available.</p>
831
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame]832<!-- ======================================================================= -->
John McCallf85e1932011-06-15 23:02:42 +0000[diff] [blame]833<h2 id="objc_arc">Automatic reference counting </h2>
834<!-- ======================================================================= -->
835
836<p>Clang provides support for <a href="AutomaticReferenceCounting.html">automated reference counting</a> in Objective-C, which eliminates the need for manual retain/release/autorelease message sends. There are two feature macros associated with automatic reference counting: <code>__has_feature(objc_arc)</code> indicates the availability of automated reference counting in general, while <code>__has_feature(objc_arc_weak)</code> indicates that automated reference counting also includes support for <code>__weak</code> pointers to Objective-C objects.</p>
837
838<!-- ======================================================================= -->
Douglas Gregor5471bc82011-09-08 17:18:35 +0000[diff] [blame]839<h2 id="objc_fixed_enum">Enumerations with a fixed underlying type</h2>
840<!-- ======================================================================= -->
841
David Blaikie5090e9f2011-10-18 05:49:30 +0000[diff] [blame]842<p>Clang provides support for C++11 enumerations with a fixed
Douglas Gregor5471bc82011-09-08 17:18:35 +0000[diff] [blame]843underlying type within Objective-C. For example, one can write an
844enumeration type as:</p>
845
846<pre>
847typedef enum : unsigned char { Red, Green, Blue } Color;
848</pre>
849
850<p>This specifies that the underlying type, which is used to store the
851enumeration value, is <tt>unsigned char</tt>.</p>
852
853<p>Use <tt>__has_feature(objc_fixed_enum)</tt> to determine whether
854support for fixed underlying types is available in Objective-C.</p>
855
856<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]857<h2 id="overloading-in-c">Function Overloading in C</h2>
858<!-- ======================================================================= -->
859
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]860<p>Clang provides support for C++ function overloading in C. Function
861overloading in C is introduced using the <tt>overloadable</tt> attribute. For
862example, one might provide several overloaded versions of a <tt>tgsin</tt>
863function that invokes the appropriate standard function computing the sine of a
864value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
865precision:</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]866
867<blockquote>
868<pre>
869#include &lt;math.h&gt;
870float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
871double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
872long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
873</pre>
874</blockquote>
875
876<p>Given these declarations, one can call <tt>tgsin</tt> with a
877<tt>float</tt> value to receive a <tt>float</tt> result, with a
878<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
879overloading in C follows the rules of C++ function overloading to pick
880the best overload given the call arguments, with a few C-specific
881semantics:</p>
882<ul>
883 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
884 double</tt> is ranked as a floating-point promotion (per C99) rather
885 than as a floating-point conversion (as in C++).</li>
886
887 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
888 <tt>U*</tt> is considered a pointer conversion (with conversion
889 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
890
891 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
892 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
893 conversion is given "conversion" rank.</li>
894</ul>
895
896<p>The declaration of <tt>overloadable</tt> functions is restricted to
897function declarations and definitions. Most importantly, if any
898function with a given name is given the <tt>overloadable</tt>
899attribute, then all function declarations and definitions with that
900name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]901attribute. This rule even applies to redeclarations of functions whose original
902declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]903
904<blockquote>
905<pre>
906int f(int) __attribute__((overloadable));
907float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
908
909int g(int) __attribute__((overloadable));
910int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
911</pre>
912</blockquote>
913
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]914<p>Functions marked <tt>overloadable</tt> must have
915prototypes. Therefore, the following code is ill-formed:</p>
916
917<blockquote>
918<pre>
919int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
920</pre>
921</blockquote>
922
923<p>However, <tt>overloadable</tt> functions are allowed to use a
924ellipsis 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>
925
926<blockquote>
927<pre>
Chris Lattner02246802009-02-18 22:27:46 +0000[diff] [blame]928void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]929</pre>
930</blockquote>
931
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]932<p>Functions declared with the <tt>overloadable</tt> attribute have
933their names mangled according to the same rules as C++ function
934names. For example, the three <tt>tgsin</tt> functions in our
935motivating example get the mangled names <tt>_Z5tgsinf</tt>,
Chris Lattner71b48d62010-11-28 18:19:13 +0000[diff] [blame]936<tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]937caveats to this use of name mangling:</p>
938
939<ul>
940
941 <li>Future versions of Clang may change the name mangling of
942 functions overloaded in C, so you should not depend on an specific
943 mangling. To be completely safe, we strongly urge the use of
944 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
945
946 <li>The <tt>overloadable</tt> attribute has almost no meaning when
947 used in C++, because names will already be mangled and functions are
948 already overloadable. However, when an <tt>overloadable</tt>
949 function occurs within an <tt>extern "C"</tt> linkage specification,
950 it's name <i>will</i> be mangled in the same way as it would in
951 C.</li>
952</ul>
953
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]954<p>Query for this feature with __has_extension(attribute_overloadable).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]955
Eli Friedman0c706c22011-09-19 23:17:44 +0000[diff] [blame]956<!-- ======================================================================= -->
957<h2 id="complex-list-init">Initializer lists for complex numbers in C</h2>
958<!-- ======================================================================= -->
959
960<p>clang supports an extension which allows the following in C:</p>
961
962<blockquote>
963<pre>
964#include &lt;math.h&gt;
965#include &lt;complex.h&gt;
966complex float x = { 1.0f, INFINITY }; // Init to (1, Inf)
967</pre>
968</blockquote>
969
970<p>This construct is useful because there is no way to separately
971initialize the real and imaginary parts of a complex variable in
972standard C, given that clang does not support <code>_Imaginary</code>.
973(clang also supports the <code>__real__</code> and <code>__imag__</code>
974extensions from gcc, which help in some cases, but are not usable in
975static initializers.)
976
977<p>Note that this extension does not allow eliding the braces; the
978meaning of the following two lines is different:</p>
979
980<blockquote>
981<pre>
982complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1)
983complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0)
984</pre>
985</blockquote>
986
987<p>This extension also works in C++ mode, as far as that goes, but does not
988 apply to the C++ <code>std::complex</code>. (In C++11, list
989 initialization allows the same syntax to be used with
990 <code>std::complex</code> with the same meaning.)
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]991
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]992<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]993<h2 id="builtins">Builtin Functions</h2>
994<!-- ======================================================================= -->
995
996<p>Clang supports a number of builtin library functions with the same syntax as
997GCC, including things like <tt>__builtin_nan</tt>,
998<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
999<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
1000addition to the GCC builtins, Clang supports a number of builtins that GCC does
1001not, which are listed here.</p>
1002
1003<p>Please note that Clang does not and will not support all of the GCC builtins
1004for vector operations. Instead of using builtins, you should use the functions
1005defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
1006define portable wrappers for these. Many of the Clang versions of these
1007functions are implemented directly in terms of <a href="#vectors">extended
1008vector support</a> instead of builtins, in order to reduce the number of
1009builtins that we need to implement.</p>
1010
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1011<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]1012<h3><a name="__builtin_shufflevector">__builtin_shufflevector</a></h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1013<!-- ======================================================================= -->
1014
Chris Lattneraad826b2009-09-16 18:56:12 +0000[diff] [blame]1015<p><tt>__builtin_shufflevector</tt> is used to express generic vector
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]1016permutation/shuffle/swizzle operations. This builtin is also very important for
1017the implementation of various target-specific header files like
1018<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1019</p>
1020
1021<p><b>Syntax:</b></p>
1022
1023<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]1024__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1025</pre>
1026
1027<p><b>Examples:</b></p>
1028
1029<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]1030 // Identity operation - return 4-element vector V1.
1031 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
1032
1033 // "Splat" element 0 of V1 into a 4-element result.
1034 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
1035
1036 // Reverse 4-element vector V1.
1037 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
1038
1039 // Concatenate every other element of 4-element vectors V1 and V2.
1040 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
1041
1042 // Concatenate every other element of 8-element vectors V1 and V2.
1043 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1044</pre>
1045
1046<p><b>Description:</b></p>
1047
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]1048<p>The first two arguments to __builtin_shufflevector are vectors that have the
1049same element type. The remaining arguments are a list of integers that specify
1050the elements indices of the first two vectors that should be extracted and
1051returned in a new vector. These element indices are numbered sequentially
1052starting with the first vector, continuing into the second vector. Thus, if
1053vec1 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]1054</p>
1055
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]1056<p>The result of __builtin_shufflevector is a vector
1057with the same element type as vec1/vec2 but that has an element count equal to
1058the number of indices specified.
1059</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1060
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]1061<p>Query for this feature with __has_builtin(__builtin_shufflevector).</p>
1062
1063<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]1064<h3><a name="__builtin_unreachable">__builtin_unreachable</a></h3>
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]1065<!-- ======================================================================= -->
1066
1067<p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in
1068the program cannot be reached, even if the compiler might otherwise think it
1069can. This is useful to improve optimization and eliminates certain warnings.
1070For example, without the <tt>__builtin_unreachable</tt> in the example below,
1071the compiler assumes that the inline asm can fall through and prints a "function
1072declared 'noreturn' should not return" warning.
1073</p>
1074
1075<p><b>Syntax:</b></p>
1076
1077<pre>
1078__builtin_unreachable()
1079</pre>
1080
1081<p><b>Example of Use:</b></p>
1082
1083<pre>
1084void myabort(void) __attribute__((noreturn));
1085void myabort(void) {
1086 asm("int3");
1087 __builtin_unreachable();
1088}
1089</pre>
1090
1091<p><b>Description:</b></p>
1092
1093<p>The __builtin_unreachable() builtin has completely undefined behavior. Since
1094it has undefined behavior, it is a statement that it is never reached and the
1095optimizer can take advantage of this to produce better code. This builtin takes
1096no arguments and produces a void result.
1097</p>
1098
1099<p>Query for this feature with __has_builtin(__builtin_unreachable).</p>
1100
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]1101<!-- ======================================================================= -->
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]1102<h3><a name="__sync_swap">__sync_swap</a></h3>
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]1103<!-- ======================================================================= -->
1104
1105<p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in
1106memory.
1107</p>
1108
1109<p><b>Syntax:</b></p>
1110
1111<pre>
1112<i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...)
1113</pre>
1114
1115<p><b>Example of Use:</b></p>
1116
1117<pre>
Sean Hunt7e98b472011-06-23 01:21:01 +0000[diff] [blame]1118int old_value = __sync_swap(&amp;value, new_value);
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]1119</pre>
1120
1121<p><b>Description:</b></p>
1122
1123<p>The __sync_swap() builtin extends the existing __sync_*() family of atomic
1124intrinsics to allow code to atomically swap the current value with the new
1125value. More importantly, it helps developers write more efficient and correct
1126code by avoiding expensive loops around __sync_bool_compare_and_swap() or
1127relying on the platform specific implementation details of
1128__sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier.
1129</p>
1130
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]1131
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]1132<!-- ======================================================================= -->
1133<h2 id="targetspecific">Target-Specific Extensions</h2>
1134<!-- ======================================================================= -->
1135
1136<p>Clang supports some language features conditionally on some targets.</p>
1137
1138<!-- ======================================================================= -->
1139<h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
1140<!-- ======================================================================= -->
1141
1142<p>The X86 backend has these language extensions:</p>
1143
1144<!-- ======================================================================= -->
1145<h4 id="x86-gs-segment">Memory references off the GS segment</h4>
1146<!-- ======================================================================= -->
1147
1148<p>Annotating a pointer with address space #256 causes it to be code generated
Chris Lattnera021e7c2009-05-05 18:54:47 +0000[diff] [blame]1149relative to the X86 GS segment register, and address space #257 causes it to be
1150relative to the X86 FS segment. Note that this is a very very low-level
1151feature that should only be used if you know what you're doing (for example in
1152an OS kernel).</p>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]1153
1154<p>Here is an example:</p>
1155
1156<pre>
1157#define GS_RELATIVE __attribute__((address_space(256)))
1158int foo(int GS_RELATIVE *P) {
1159 return *P;
1160}
1161</pre>
1162
1163<p>Which compiles to (on X86-32):</p>
1164
1165<pre>
1166_foo:
1167 movl 4(%esp), %eax
1168 movl %gs:(%eax), %eax
1169 ret
1170</pre>
1171
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1172<!-- ======================================================================= -->
1173<h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
1174<!-- ======================================================================= -->
1175
1176<p>Clang supports additional attributes that are useful for documenting program
1177invariants and rules for static analysis tools. The extensions documented here
1178are used by the <a
1179href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
1180engine</a> that is part of Clang's Analysis library.</p>
1181
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1182<h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1183
1184<p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
Ted Kremenek4df21142009-04-10 05:04:22 +0000[diff] [blame]1185attribute. This attribute, which is typically affixed to a function prototype,
1186indicates that a call to a given function never returns. Function prototypes for
1187common functions like <tt>exit</tt> are typically annotated with this attribute,
1188as well as a variety of common assertion handlers. Users can educate the static
1189analyzer about their own custom assertion handles (thus cutting down on false
1190positives due to false paths) by marking their own &quot;panic&quot; functions
1191with this attribute.</p>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1192
1193<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
Nick Lewycky625b5862009-06-14 04:08:08 +0000[diff] [blame]1194there are special functions that for all intents and purposes should be
1195considered panic functions (i.e., they are only called when an internal program
1196error occurs) but may actually return so that the program can fail gracefully.
1197The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
1198as being interpreted as &quot;no return&quot; functions by the analyzer (thus
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]1199pruning bogus paths) but will not affect compilation (as in the case of
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1200<tt>noreturn</tt>).</p>
1201
1202<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]1203same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1204placed at the end of function prototypes:</p>
1205
1206<pre>
1207 void foo() <b>__attribute__((analyzer_noreturn))</b>;
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]1208</pre>
1209
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1210<p>Query for this feature with
1211<tt>__has_attribute(analyzer_noreturn)</tt>.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]1212
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1213<h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3>
1214
1215<p>Many methods in Objective-C have conventional meanings determined
1216by their selectors. For the purposes of static analysis, it is
1217sometimes useful to be able to mark a method as having a particular
1218conventional meaning despite not having the right selector, or as not
1219having the conventional meaning that its selector would suggest.
1220For these use cases, we provide an attribute to specifically describe
1221the <q>method family</q> that a method belongs to.</p>
1222
1223<p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>,
1224where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>,
1225<tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>. This attribute
1226can only be placed at the end of a method declaration:</p>
1227
1228<pre>
1229 - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>;
1230</pre>
1231
1232<p>Users who do not wish to change the conventional meaning of a
1233method, and who merely want to document its non-standard retain and
1234release semantics, should use the
1235<a href="#attr_retain_release">retaining behavior attributes</a>
1236described below.</p>
1237
1238<p>Query for this feature with
1239<tt>__has_attribute(objc_method_family)</tt>.</p>
1240
1241<h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]1242
1243<p>In Objective-C, functions and methods are generally assumed to take
1244and return objects with +0 retain counts, with some exceptions for
1245special methods like <tt>+alloc</tt> and <tt>init</tt>. However,
1246there are exceptions, and so Clang provides attributes to allow these
1247exceptions to be documented, which helps the analyzer find leaks (and
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1248ignore non-leaks). Some exceptions may be better described using
1249the <a href="#attr_method_family"><tt>objc_method_family</tt></a>
1250attribute instead.</p>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]1251
1252<p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>,
1253<tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>,
1254and <tt>cf_returns_not_retained</tt> attributes can be placed on
1255methods and functions that return Objective-C or CoreFoundation
1256objects. They are commonly placed at the end of a function prototype
1257or method declaration:</p>
1258
1259<pre>
1260 id foo() <b>__attribute__((ns_returns_retained))</b>;
1261
1262 - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>;
1263</pre>
1264
1265<p>The <tt>*_returns_retained</tt> attributes specify that the
1266returned object has a +1 retain count.
1267The <tt>*_returns_not_retained</tt> attributes specify that the return
1268object has a +0 retain count, even if the normal convention for its
1269selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the
1270returned object is +0, but is guaranteed to live at least as long as the
1271next flush of an autorelease pool.</p>
1272
1273<p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt>
1274attributes can be placed on an parameter declaration; they specify
1275that the argument is expected to have a +1 retain count, which will be
1276balanced in some way by the function or method.
1277The <tt>ns_consumes_self</tt> attribute can only be placed on an
1278Objective-C method; it specifies that the method expects
1279its <tt>self</tt> parameter to have a +1 retain count, which it will
1280balance in some way.</p>
1281
1282<pre>
1283 void <b>foo(__attribute__((ns_consumed))</b> NSString *string);
1284
1285 - (void) bar <b>__attribute__((ns_consumes_self))</b>;
1286 - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x;
1287</pre>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1288
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1289<p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>,
1290<tt>__has_attribute(ns_returns_retained)</tt>, etc.</p>
1291
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]1292<!-- ======================================================================= -->
1293<h2 id="dynamicanalyzerspecific">Dynamic Analysis-Specific Extensions</h2>
1294<!-- ======================================================================= -->
1295<h3 id="address_sanitizer">AddressSanitizer</h3>
1296<p> Use <code>__has_feature(address_sanitizer)</code>
1297to check if the code is being built with <a
1298 href="AddressSanitizer.html">AddressSanitizer</a>.
1299</p>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1300
1301<!-- ======================================================================= -->
Caitlin Sadowski73cbbc82011-07-28 18:38:36 +0000[diff] [blame]1302<h2 id="threadsafety">Thread-Safety Annotation Checking</h2>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1303<!-- ======================================================================= -->
1304
1305<p>Clang supports additional attributes for checking basic locking policies in
1306multithreaded programs.
1307Clang currently parses the following list of attributes, although
1308<b>the implementation for these annotations is currently in development.</b>
1309For more details, see the
1310<a href="http://gcc.gnu.org/wiki/ThreadSafetyAnnotation">GCC implementation</a>.
1311</p>
1312
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1313<h4 id="ts_noanal">no_thread_safety_analysis</h4>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1314
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1315<p>Use <tt>__attribute__((no_thread_safety_analysis))</tt> on a function
1316declaration to specify that the thread safety analysis should not be run on that
1317function. This attribute provides an escape hatch (e.g. for situations when it
1318is difficult to annotate the locking policy). </p>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1319
1320<h4 id="ts_lockable">lockable</h4>
1321
1322<p>Use <tt>__attribute__((lockable))</tt> on a class definition to specify
1323that it has a lockable type (e.g. a Mutex class). This annotation is primarily
1324used to check consistency.</p>
1325
1326<h4 id="ts_scopedlockable">scoped_lockable</h4>
1327
1328<p>Use <tt>__attribute__((scoped_lockable))</tt> on a class definition to
1329specify that it has a "scoped" lockable type. Objects of this type will acquire
1330the lock upon construction and release it upon going out of scope.
1331 This annotation is primarily used to check
1332consistency.</p>
1333
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1334<h4 id="ts_guardedvar">guarded_var</h4>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1335
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1336<p>Use <tt>__attribute__((guarded_var))</tt> on a variable declaration to
1337specify that the variable must be accessed while holding some lock.</p>
1338
1339<h4 id="ts_ptguardedvar">pt_guarded_var</h4>
1340
1341<p>Use <tt>__attribute__((pt_guarded_var))</tt> on a pointer declaration to
1342specify that the pointer must be dereferenced while holding some lock.</p>
1343
1344<h4 id="ts_guardedby">guarded_by(l)</h4>
1345
1346<p>Use <tt>__attribute__((guarded_by(l)))</tt> on a variable declaration to
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1347specify that the variable must be accessed while holding lock <tt>l</tt>.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1348
1349<h4 id="ts_ptguardedby">pt_guarded_by(l)</h4>
1350
1351<p>Use <tt>__attribute__((pt_guarded_by(l)))</tt> on a pointer declaration to
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1352specify that the pointer must be dereferenced while holding lock <tt>l</tt>.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1353
1354<h4 id="ts_acquiredbefore">acquired_before(...)</h4>
1355
1356<p>Use <tt>__attribute__((acquired_before(...)))</tt> on a declaration
1357of a lockable variable to specify that the lock must be acquired before all
1358attribute arguments. Arguments must be lockable type, and there must be at
1359least one argument.</p>
1360
1361<h4 id="ts_acquiredafter">acquired_after(...)</h4>
1362
1363<p>Use <tt>__attribute__((acquired_after(...)))</tt> on a declaration
1364of a lockable variable to specify that the lock must be acquired after all
1365attribute arguments. Arguments must be lockable type, and there must be at
1366least one argument.</p>
1367
1368<h4 id="ts_elf">exclusive_lock_function(...)</h4>
1369
1370<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
1371declaration to specify that the function acquires all listed locks
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1372exclusively. This attribute takes zero or more arguments: either of lockable
1373type or integers indexing into function parameters of lockable type. If no
1374arguments are given, the acquired lock is implicitly <tt>this</tt> of the
1375enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1376
1377<h4 id="ts_slf">shared_lock_function(...)</h4>
1378
1379<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
1380declaration to specify that the function acquires all listed locks, although
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1381 the locks may be shared (e.g. read locks). This attribute takes zero or more
1382arguments: either of lockable type or integers indexing into function
1383parameters of lockable type. If no arguments are given, the acquired lock is
1384implicitly <tt>this</tt> of the enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1385
1386<h4 id="ts_etf">exclusive_trylock_function(...)</h4>
1387
1388<p>Use <tt>__attribute__((exclusive_lock_function(...)))</tt> on a function
1389declaration to specify that the function will try (without blocking) to acquire
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1390all listed locks exclusively. This attribute takes one or more arguments. The
1391first argument is an integer or boolean value specifying the return value of a
1392successful lock acquisition. The remaining arugments are either of lockable type
1393or integers indexing into function parameters of lockable type. If only one
1394argument is given, the acquired lock is implicitly <tt>this</tt> of the
1395enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1396
1397<h4 id="ts_stf">shared_trylock_function(...)</h4>
1398
1399<p>Use <tt>__attribute__((shared_lock_function(...)))</tt> on a function
1400declaration to specify that the function will try (without blocking) to acquire
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1401all listed locks, although the locks may be shared (e.g. read locks). This
1402attribute takes one or more arguments. The first argument is an integer or
1403boolean value specifying the return value of a successful lock acquisition. The
1404remaining arugments are either of lockable type or integers indexing into
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1405function parameters of lockable type. If only one argument is given, the
1406acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
1407
1408<h4 id="ts_uf">unlock_function(...)</h4>
1409
1410<p>Use <tt>__attribute__((unlock_function(...)))</tt> on a function
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1411declaration to specify that the function release all listed locks. This
1412attribute takes zero or more arguments: either of lockable type or integers
1413indexing into function parameters of lockable type. If no arguments are given,
1414the acquired lock is implicitly <tt>this</tt> of the enclosing object.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1415
1416<h4 id="ts_lr">lock_returned(l)</h4>
1417
1418<p>Use <tt>__attribute__((lock_returned(l)))</tt> on a function
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1419declaration to specify that the function returns lock <tt>l</tt> (<tt>l</tt>
1420must be of lockable type). This annotation is used to aid in resolving lock
1421expressions.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1422
1423<h4 id="ts_le">locks_excluded(...)</h4>
1424
1425<p>Use <tt>__attribute__((locks_excluded(...)))</tt> on a function declaration
Caitlin Sadowskib51e0312011-08-09 17:59:31 +0000[diff] [blame]1426to specify that the function must not be called with the listed locks. Arguments
1427must be lockable type, and there must be at least one argument.</p>
Caitlin Sadowskidb33e142011-07-28 20:12:35 +0000[diff] [blame]1428
1429<h4 id="ts_elr">exclusive_locks_required(...)</h4>
1430
1431<p>Use <tt>__attribute__((exclusive_locks_required(...)))</tt> on a function
1432declaration to specify that the function must be called while holding the listed
1433exclusive locks. Arguments must be lockable type, and there must be at
1434least one argument.</p>
1435
1436<h4 id="ts_slr">shared_locks_required(...)</h4>
1437
1438<p>Use <tt>__attribute__((shared_locks_required(...)))</tt> on a function
1439declaration to specify that the function must be called while holding the listed
1440shared locks. Arguments must be lockable type, and there must be at
1441least one argument.</p>
Caitlin Sadowskifdde9e72011-07-28 17:21:07 +0000[diff] [blame]1442
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1443</div>
1444</body>
1445</html>