[www-releases] r297634 - Check in the 4.0.0 release

Hans Wennborg via llvm-commits llvm-commits at lists.llvm.org
Mon Mar 13 09:30:21 PDT 2017


Added: www-releases/trunk/4.0.0/tools/clang/docs/AttributeReference.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/AttributeReference.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/AttributeReference.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/AttributeReference.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,5234 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Attributes in Clang — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="next" title="Diagnostic flags in Clang" href="DiagnosticsReference.html" />
+    <link rel="prev" title="Objective-C Automatic Reference Counting (ARC)" href="AutomaticReferenceCounting.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Attributes in Clang</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DiagnosticsReference.html">Diagnostic flags in Clang</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="attributes-in-clang">
+<h1>Attributes in Clang<a class="headerlink" href="#attributes-in-clang" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id6">Introduction</a></li>
+<li><a class="reference internal" href="#function-attributes" id="id7">Function Attributes</a><ul>
+<li><a class="reference internal" href="#interrupt" id="id8">interrupt</a></li>
+<li><a class="reference internal" href="#abi-tag-gnu-abi-tag" id="id9">abi_tag (gnu::abi_tag)</a></li>
+<li><a class="reference internal" href="#acquire-capability-acquire-shared-capability-clang-acquire-capability-clang-acquire-shared-capability" id="id10">acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)</a></li>
+<li><a class="reference internal" href="#alloc-size-gnu-alloc-size" id="id11">alloc_size (gnu::alloc_size)</a></li>
+<li><a class="reference internal" href="#id1" id="id12">interrupt</a></li>
+<li><a class="reference internal" href="#assert-capability-assert-shared-capability-clang-assert-capability-clang-assert-shared-capability" id="id13">assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)</a></li>
+<li><a class="reference internal" href="#assume-aligned-gnu-assume-aligned" id="id14">assume_aligned (gnu::assume_aligned)</a></li>
+<li><a class="reference internal" href="#availability" id="id15">availability</a></li>
+<li><a class="reference internal" href="#noreturn" id="id16">_Noreturn</a></li>
+<li><a class="reference internal" href="#id2" id="id17">noreturn</a></li>
+<li><a class="reference internal" href="#carries-dependency" id="id18">carries_dependency</a></li>
+<li><a class="reference internal" href="#convergent-clang-convergent" id="id19">convergent (clang::convergent)</a></li>
+<li><a class="reference internal" href="#deprecated-gnu-deprecated" id="id20">deprecated (gnu::deprecated)</a></li>
+<li><a class="reference internal" href="#diagnose-if" id="id21">diagnose_if</a></li>
+<li><a class="reference internal" href="#disable-tail-calls-clang-disable-tail-calls" id="id22">disable_tail_calls (clang::disable_tail_calls)</a></li>
+<li><a class="reference internal" href="#enable-if" id="id23">enable_if</a></li>
+<li><a class="reference internal" href="#flatten-gnu-flatten" id="id24">flatten (gnu::flatten)</a></li>
+<li><a class="reference internal" href="#format-gnu-format" id="id25">format (gnu::format)</a></li>
+<li><a class="reference internal" href="#ifunc-gnu-ifunc" id="id26">ifunc (gnu::ifunc)</a></li>
+<li><a class="reference internal" href="#internal-linkage-clang-internal-linkage" id="id27">internal_linkage (clang::internal_linkage)</a></li>
+<li><a class="reference internal" href="#id3" id="id28">interrupt</a></li>
+<li><a class="reference internal" href="#noalias" id="id29">noalias</a></li>
+<li><a class="reference internal" href="#noduplicate-clang-noduplicate" id="id30">noduplicate (clang::noduplicate)</a></li>
+<li><a class="reference internal" href="#no-sanitize-clang-no-sanitize" id="id31">no_sanitize (clang::no_sanitize)</a></li>
+<li><a class="reference internal" href="#no-sanitize-address-no-address-safety-analysis-gnu-no-address-safety-analysis-gnu-no-sanitize-address" id="id32">no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)</a></li>
+<li><a class="reference internal" href="#no-sanitize-thread" id="id33">no_sanitize_thread</a></li>
+<li><a class="reference internal" href="#no-sanitize-memory" id="id34">no_sanitize_memory</a></li>
+<li><a class="reference internal" href="#no-split-stack-gnu-no-split-stack" id="id35">no_split_stack (gnu::no_split_stack)</a></li>
+<li><a class="reference internal" href="#not-tail-called-clang-not-tail-called" id="id36">not_tail_called (clang::not_tail_called)</a></li>
+<li><a class="reference internal" href="#pragma-omp-declare-simd" id="id37">#pragma omp declare simd</a></li>
+<li><a class="reference internal" href="#pragma-omp-declare-target" id="id38">#pragma omp declare target</a></li>
+<li><a class="reference internal" href="#objc-boxable" id="id39">objc_boxable</a></li>
+<li><a class="reference internal" href="#objc-method-family" id="id40">objc_method_family</a></li>
+<li><a class="reference internal" href="#objc-requires-super" id="id41">objc_requires_super</a></li>
+<li><a class="reference internal" href="#objc-runtime-name" id="id42">objc_runtime_name</a></li>
+<li><a class="reference internal" href="#objc-runtime-visible" id="id43">objc_runtime_visible</a></li>
+<li><a class="reference internal" href="#optnone-clang-optnone" id="id44">optnone (clang::optnone)</a></li>
+<li><a class="reference internal" href="#overloadable" id="id45">overloadable</a></li>
+<li><a class="reference internal" href="#release-capability-release-shared-capability-clang-release-capability-clang-release-shared-capability" id="id46">release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)</a></li>
+<li><a class="reference internal" href="#kernel" id="id47">kernel</a></li>
+<li><a class="reference internal" href="#target-gnu-target" id="id48">target (gnu::target)</a></li>
+<li><a class="reference internal" href="#try-acquire-capability-try-acquire-shared-capability-clang-try-acquire-capability-clang-try-acquire-shared-capability" id="id49">try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)</a></li>
+<li><a class="reference internal" href="#nodiscard-warn-unused-result-clang-warn-unused-result-gnu-warn-unused-result" id="id50">nodiscard, warn_unused_result, clang::warn_unused_result, gnu::warn_unused_result</a></li>
+<li><a class="reference internal" href="#xray-always-instrument-clang-xray-always-instrument-xray-never-instrument-clang-xray-never-instrument" id="id51">xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#variable-attributes" id="id52">Variable Attributes</a><ul>
+<li><a class="reference internal" href="#dllexport-gnu-dllexport" id="id53">dllexport (gnu::dllexport)</a></li>
+<li><a class="reference internal" href="#dllimport-gnu-dllimport" id="id54">dllimport (gnu::dllimport)</a></li>
+<li><a class="reference internal" href="#init-seg" id="id55">init_seg</a></li>
+<li><a class="reference internal" href="#nodebug-gnu-nodebug" id="id56">nodebug (gnu::nodebug)</a></li>
+<li><a class="reference internal" href="#nosvm" id="id57">nosvm</a></li>
+<li><a class="reference internal" href="#pass-object-size" id="id58">pass_object_size</a></li>
+<li><a class="reference internal" href="#require-constant-initialization-clang-require-constant-initialization" id="id59">require_constant_initialization (clang::require_constant_initialization)</a></li>
+<li><a class="reference internal" href="#section-gnu-section-declspec-allocate" id="id60">section (gnu::section, __declspec(allocate))</a></li>
+<li><a class="reference internal" href="#swiftcall-gnu-swiftcall" id="id61">swiftcall (gnu::swiftcall)</a></li>
+<li><a class="reference internal" href="#swift-context-gnu-swift-context" id="id62">swift_context (gnu::swift_context)</a></li>
+<li><a class="reference internal" href="#swift-error-result-gnu-swift-error-result" id="id63">swift_error_result (gnu::swift_error_result)</a></li>
+<li><a class="reference internal" href="#swift-indirect-result-gnu-swift-indirect-result" id="id64">swift_indirect_result (gnu::swift_indirect_result)</a></li>
+<li><a class="reference internal" href="#tls-model-gnu-tls-model" id="id65">tls_model (gnu::tls_model)</a></li>
+<li><a class="reference internal" href="#thread" id="id66">thread</a></li>
+<li><a class="reference internal" href="#maybe-unused-unused-gnu-unused" id="id67">maybe_unused, unused, gnu::unused</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#type-attributes" id="id68">Type Attributes</a><ul>
+<li><a class="reference internal" href="#align-value" id="id69">align_value</a></li>
+<li><a class="reference internal" href="#empty-bases" id="id70">empty_bases</a></li>
+<li><a class="reference internal" href="#flag-enum" id="id71">flag_enum</a></li>
+<li><a class="reference internal" href="#lto-visibility-public-clang-lto-visibility-public" id="id72">lto_visibility_public (clang::lto_visibility_public)</a></li>
+<li><a class="reference internal" href="#layout-version" id="id73">layout_version</a></li>
+<li><a class="reference internal" href="#single-inhertiance-multiple-inheritance-virtual-inheritance" id="id74">__single_inhertiance, __multiple_inheritance, __virtual_inheritance</a></li>
+<li><a class="reference internal" href="#novtable" id="id75">novtable</a></li>
+<li><a class="reference internal" href="#objc-subclassing-restricted" id="id76">objc_subclassing_restricted</a></li>
+<li><a class="reference internal" href="#transparent-union-gnu-transparent-union" id="id77">transparent_union (gnu::transparent_union)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#statement-attributes" id="id78">Statement Attributes</a><ul>
+<li><a class="reference internal" href="#fallthrough-clang-fallthrough" id="id79">fallthrough, clang::fallthrough</a></li>
+<li><a class="reference internal" href="#pragma-clang-loop" id="id80">#pragma clang loop</a></li>
+<li><a class="reference internal" href="#pragma-unroll-pragma-nounroll" id="id81">#pragma unroll, #pragma nounroll</a></li>
+<li><a class="reference internal" href="#read-only-write-only-read-write-read-only-write-only-read-write" id="id82">__read_only, __write_only, __read_write (read_only, write_only, read_write)</a></li>
+<li><a class="reference internal" href="#attribute-opencl-unroll-hint" id="id83">__attribute__((opencl_unroll_hint))</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#type-safety-checking" id="id84">Type Safety Checking</a><ul>
+<li><a class="reference internal" href="#argument-with-type-tag" id="id85">argument_with_type_tag</a></li>
+<li><a class="reference internal" href="#pointer-with-type-tag" id="id86">pointer_with_type_tag</a></li>
+<li><a class="reference internal" href="#type-tag-for-datatype" id="id87">type_tag_for_datatype</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#amd-gpu-attributes" id="id88">AMD GPU Attributes</a><ul>
+<li><a class="reference internal" href="#amdgpu-flat-work-group-size" id="id89">amdgpu_flat_work_group_size</a></li>
+<li><a class="reference internal" href="#amdgpu-num-sgpr" id="id90">amdgpu_num_sgpr</a></li>
+<li><a class="reference internal" href="#amdgpu-num-vgpr" id="id91">amdgpu_num_vgpr</a></li>
+<li><a class="reference internal" href="#amdgpu-waves-per-eu" id="id92">amdgpu_waves_per_eu</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#calling-conventions" id="id93">Calling Conventions</a><ul>
+<li><a class="reference internal" href="#fastcall-gnu-fastcall-fastcall-fastcall" id="id94">fastcall (gnu::fastcall, __fastcall, _fastcall)</a></li>
+<li><a class="reference internal" href="#ms-abi-gnu-ms-abi" id="id95">ms_abi (gnu::ms_abi)</a></li>
+<li><a class="reference internal" href="#pcs-gnu-pcs" id="id96">pcs (gnu::pcs)</a></li>
+<li><a class="reference internal" href="#preserve-all" id="id97">preserve_all</a></li>
+<li><a class="reference internal" href="#preserve-most" id="id98">preserve_most</a></li>
+<li><a class="reference internal" href="#regcall-gnu-regcall-regcall" id="id99">regcall (gnu::regcall, __regcall)</a></li>
+<li><a class="reference internal" href="#regparm-gnu-regparm" id="id100">regparm (gnu::regparm)</a></li>
+<li><a class="reference internal" href="#stdcall-gnu-stdcall-stdcall-stdcall" id="id101">stdcall (gnu::stdcall, __stdcall, _stdcall)</a></li>
+<li><a class="reference internal" href="#thiscall-gnu-thiscall-thiscall-thiscall" id="id102">thiscall (gnu::thiscall, __thiscall, _thiscall)</a></li>
+<li><a class="reference internal" href="#vectorcall-vectorcall-vectorcall" id="id103">vectorcall (__vectorcall, _vectorcall)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#consumed-annotation-checking" id="id104">Consumed Annotation Checking</a><ul>
+<li><a class="reference internal" href="#callable-when" id="id105">callable_when</a></li>
+<li><a class="reference internal" href="#consumable" id="id106">consumable</a></li>
+<li><a class="reference internal" href="#param-typestate" id="id107">param_typestate</a></li>
+<li><a class="reference internal" href="#return-typestate" id="id108">return_typestate</a></li>
+<li><a class="reference internal" href="#set-typestate" id="id109">set_typestate</a></li>
+<li><a class="reference internal" href="#test-typestate" id="id110">test_typestate</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-address-spaces" id="id111">OpenCL Address Spaces</a><ul>
+<li><a class="reference internal" href="#constant-constant" id="id112">constant (__constant)</a></li>
+<li><a class="reference internal" href="#generic-generic" id="id113">generic (__generic)</a></li>
+<li><a class="reference internal" href="#global-global" id="id114">global (__global)</a></li>
+<li><a class="reference internal" href="#local-local" id="id115">local (__local)</a></li>
+<li><a class="reference internal" href="#private-private" id="id116">private (__private)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#nullability-attributes" id="id117">Nullability Attributes</a><ul>
+<li><a class="reference internal" href="#nonnull-gnu-nonnull" id="id118">nonnull (gnu::nonnull)</a></li>
+<li><a class="reference internal" href="#returns-nonnull-gnu-returns-nonnull" id="id119">returns_nonnull (gnu::returns_nonnull)</a></li>
+<li><a class="reference internal" href="#nonnull" id="id120">_Nonnull</a></li>
+<li><a class="reference internal" href="#null-unspecified" id="id121">_Null_unspecified</a></li>
+<li><a class="reference internal" href="#nullable" id="id122">_Nullable</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id6">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This page lists the attributes currently supported by Clang.</p>
+</div>
+<div class="section" id="function-attributes">
+<h2><a class="toc-backref" href="#id7">Function Attributes</a><a class="headerlink" href="#function-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="interrupt">
+<h3><a class="toc-backref" href="#id8">interrupt</a><a class="headerlink" href="#interrupt" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((interrupt("TYPE")))</span></tt> attribute on
+ARM targets. This attribute may be attached to a function definition and
+instructs the backend to generate appropriate function entry/exit code so that
+it can be used directly as an interrupt service routine.</p>
+<p>The parameter passed to the interrupt attribute is optional, but if
+provided it must be a string literal with one of the following values: “IRQ”,
+“FIQ”, “SWI”, “ABORT”, “UNDEF”.</p>
+<p>The semantics are as follows:</p>
+<ul>
+<li><p class="first">If the function is AAPCS, Clang instructs the backend to realign the stack to
+8 bytes on entry. This is a general requirement of the AAPCS at public
+interfaces, but may not hold when an exception is taken. Doing this allows
+other AAPCS functions to be called.</p>
+</li>
+<li><p class="first">If the CPU is M-class this is all that needs to be done since the architecture
+itself is designed in such a way that functions obeying the normal AAPCS ABI
+constraints are valid exception handlers.</p>
+</li>
+<li><p class="first">If the CPU is not M-class, the prologue and epilogue are modified to save all
+non-banked registers that are used, so that upon return the user-mode state
+will not be corrupted. Note that to avoid unnecessary overhead, only
+general-purpose (integer) registers are saved in this way. If VFP operations
+are needed, that state must be saved manually.</p>
+<p>Specifically, interrupt kinds other than “FIQ” will save all core registers
+except “lr” and “sp”. “FIQ” interrupts will save r0-r7.</p>
+</li>
+<li><p class="first">If the CPU is not M-class, the return instruction is changed to one of the
+canonical sequences permitted by the architecture for exception return. Where
+possible the function itself will make the necessary “lr” adjustments so that
+the “preferred return address” is selected.</p>
+<p>Unfortunately the compiler is unable to make this guarantee for an “UNDEF”
+handler, where the offset from “lr” to the preferred return address depends on
+the execution state of the code which generated the exception. In this case
+a sequence equivalent to “movs pc, lr” will be used.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="abi-tag-gnu-abi-tag">
+<h3><a class="toc-backref" href="#id9">abi_tag (gnu::abi_tag)</a><a class="headerlink" href="#abi-tag-gnu-abi-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">abi_tag</span></tt> attribute can be applied to a function, variable, class or
+inline namespace declaration to modify the mangled name of the entity. It gives
+the ability to distinguish between different versions of the same entity but
+with different ABI versions supported. For example, a newer version of a class
+could have a different set of data members and thus have a different size. Using
+the <tt class="docutils literal"><span class="pre">abi_tag</span></tt> attribute, it is possible to have different mangled names for
+a global variable of the class type. Therefor, the old code could keep using
+the old manged name and the new code will use the new mangled name with tags.</p>
+</div>
+<div class="section" id="acquire-capability-acquire-shared-capability-clang-acquire-capability-clang-acquire-shared-capability">
+<h3><a class="toc-backref" href="#id10">acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)</a><a class="headerlink" href="#acquire-capability-acquire-shared-capability-clang-acquire-capability-clang-acquire-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function as acquiring a capability.</p>
+</div>
+<div class="section" id="alloc-size-gnu-alloc-size">
+<h3><a class="toc-backref" href="#id11">alloc_size (gnu::alloc_size)</a><a class="headerlink" href="#alloc-size-gnu-alloc-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">alloc_size</span></tt> attribute can be placed on functions that return pointers in
+order to hint to the compiler how many bytes of memory will be available at the
+returned poiner. <tt class="docutils literal"><span class="pre">alloc_size</span></tt> takes one or two arguments.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">alloc_size(N)</span></tt> implies that argument number N equals the number of
+available bytes at the returned pointer.</li>
+<li><tt class="docutils literal"><span class="pre">alloc_size(N,</span> <span class="pre">M)</span></tt> implies that the product of argument number N and
+argument number M equals the number of available bytes at the returned
+pointer.</li>
+</ul>
+<p>Argument numbers are 1-based.</p>
+<p>An example of how to use <tt class="docutils literal"><span class="pre">alloc_size</span></tt></p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="o">*</span><span class="nf">my_malloc</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_size</span><span class="p">(</span><span class="mi">1</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">my_calloc</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">alloc_size</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+  <span class="kt">void</span> <span class="o">*</span><span class="k">const</span> <span class="n">p</span> <span class="o">=</span> <span class="n">my_malloc</span><span class="p">(</span><span class="mi">100</span><span class="p">);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="mi">100</span><span class="p">);</span>
+  <span class="kt">void</span> <span class="o">*</span><span class="k">const</span> <span class="n">a</span> <span class="o">=</span> <span class="n">my_calloc</span><span class="p">(</span><span class="mi">20</span><span class="p">,</span> <span class="mi">5</span><span class="p">);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="mi">100</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This attribute works differently in clang than it does in GCC.
+Specifically, clang will only trace <tt class="docutils literal"><span class="pre">const</span></tt> pointers (as above); we give up
+on pointers that are not marked as <tt class="docutils literal"><span class="pre">const</span></tt>. In the vast majority of cases,
+this is unimportant, because LLVM has support for the <tt class="docutils literal"><span class="pre">alloc_size</span></tt>
+attribute. However, this may cause mildly unintuitive behavior when used with
+other attributes, such as <tt class="docutils literal"><span class="pre">enable_if</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id12">interrupt</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((interrupt))</span></tt> attribute on
+x86/x86-64 targets.The compiler generates function entry and exit sequences
+suitable for use in an interrupt handler when this attribute is present.
+The ‘IRET’ instruction, instead of the ‘RET’ instruction, is used to return
+from interrupt or exception handlers.  All registers, except for the EFLAGS
+register which is restored by the ‘IRET’ instruction, are preserved by the
+compiler.</p>
+<p>Any interruptible-without-stack-switch code must be compiled with
+-mno-red-zone since interrupt handlers can and will, because of the
+hardware design, touch the red zone.</p>
+<ol class="arabic simple">
+<li>interrupt handler must be declared with a mandatory pointer argument:</li>
+</ol>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">interrupt_frame</span>
+<span class="p">{</span>
+  <span class="kt">uword_t</span> <span class="n">ip</span><span class="p">;</span>
+  <span class="kt">uword_t</span> <span class="n">cs</span><span class="p">;</span>
+  <span class="kt">uword_t</span> <span class="n">flags</span><span class="p">;</span>
+  <span class="kt">uword_t</span> <span class="n">sp</span><span class="p">;</span>
+  <span class="kt">uword_t</span> <span class="n">ss</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="n">__attribute__</span> <span class="p">((</span><span class="n">interrupt</span><span class="p">))</span>
+<span class="kt">void</span> <span class="n">f</span> <span class="p">(</span><span class="k">struct</span> <span class="n">interrupt_frame</span> <span class="o">*</span><span class="n">frame</span><span class="p">)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<ol class="arabic simple" start="2">
+<li>exception handler:</li>
+</ol>
+<blockquote>
+<div><p>The exception handler is very similar to the interrupt handler with
+a different mandatory function signature:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__attribute__</span> <span class="p">((</span><span class="n">interrupt</span><span class="p">))</span>
+<span class="kt">void</span> <span class="n">f</span> <span class="p">(</span><span class="k">struct</span> <span class="n">interrupt_frame</span> <span class="o">*</span><span class="n">frame</span><span class="p">,</span> <span class="kt">uword_t</span> <span class="n">error_code</span><span class="p">)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>and compiler pops ‘ERROR_CODE’ off stack before the ‘IRET’ instruction.</p>
+<p>The exception handler should only be used for exceptions which push an
+error code and all other exceptions must use the interrupt handler.
+The system will crash if the wrong handler is used.</p>
+</div></blockquote>
+</div>
+<div class="section" id="assert-capability-assert-shared-capability-clang-assert-capability-clang-assert-shared-capability">
+<h3><a class="toc-backref" href="#id13">assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)</a><a class="headerlink" href="#assert-capability-assert-shared-capability-clang-assert-capability-clang-assert-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.</p>
+</div>
+<div class="section" id="assume-aligned-gnu-assume-aligned">
+<h3><a class="toc-backref" href="#id14">assume_aligned (gnu::assume_aligned)</a><a class="headerlink" href="#assume-aligned-gnu-assume-aligned" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((assume_aligned(<alignment>[,<offset>]))</span></tt> on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) has the specified offset, in bytes, from an address with the
+specified alignment. The offset is taken to be zero if omitted.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// The returned pointer value has 32-byte alignment.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">a</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">assume_aligned</span> <span class="p">(</span><span class="mi">32</span><span class="p">)));</span>
+
+<span class="c1">// The returned pointer value is 4 bytes greater than an address having</span>
+<span class="c1">// 32-byte alignment.</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">b</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">assume_aligned</span> <span class="p">(</span><span class="mi">32</span><span class="p">,</span> <span class="mi">4</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>Note that this attribute provides information to the compiler regarding a
+condition that the code already ensures is true. It does not cause the compiler
+to enforce the provided alignment assumption.</p>
+</div>
+<div class="section" id="availability">
+<h3><a class="toc-backref" href="#id15">availability</a><a class="headerlink" href="#availability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">availability</span></tt> attribute can be placed on declarations to describe the
+lifecycle of that declaration relative to operating system versions.  Consider
+the function declaration for a hypothetical function <tt class="docutils literal"><span class="pre">f</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">,</span><span class="n">deprecated</span><span class="o">=</span><span class="mf">10.6</span><span class="p">,</span><span class="n">obsoleted</span><span class="o">=</span><span class="mf">10.7</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>The availability attribute states that <tt class="docutils literal"><span class="pre">f</span></tt> was introduced in Mac OS X 10.4,
+deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7.  This information
+is used by Clang to determine when it is safe to use <tt class="docutils literal"><span class="pre">f</span></tt>: for example, if
+Clang is instructed to compile code for Mac OS X 10.5, a call to <tt class="docutils literal"><span class="pre">f()</span></tt>
+succeeds.  If Clang is instructed to compile code for Mac OS X 10.6, the call
+succeeds but Clang emits a warning specifying that the function is deprecated.
+Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call
+fails because <tt class="docutils literal"><span class="pre">f()</span></tt> is no longer available.</p>
+<p>The availability attribute is a comma-separated list starting with the
+platform name and then including clauses specifying important milestones in the
+declaration’s lifetime (in any order) along with additional information.  Those
+clauses can be:</p>
+<dl class="docutils">
+<dt>introduced=<em>version</em></dt>
+<dd>The first version in which this declaration was introduced.</dd>
+<dt>deprecated=<em>version</em></dt>
+<dd>The first version in which this declaration was deprecated, meaning that
+users should migrate away from this API.</dd>
+<dt>obsoleted=<em>version</em></dt>
+<dd>The first version in which this declaration was obsoleted, meaning that it
+was removed completely and can no longer be used.</dd>
+<dt>unavailable</dt>
+<dd>This declaration is never available on this platform.</dd>
+<dt>message=<em>string-literal</em></dt>
+<dd>Additional message text that Clang will provide when emitting a warning or
+error about use of a deprecated or obsoleted declaration.  Useful to direct
+users to replacement APIs.</dd>
+<dt>replacement=<em>string-literal</em></dt>
+<dd>Additional message text that Clang will use to provide Fix-It when emitting
+a warning about use of a deprecated declaration. The Fix-It will replace
+the deprecated declaration with the new declaration specified.</dd>
+</dl>
+<p>Multiple availability attributes can be placed on a declaration, which may
+correspond to different platforms.  Only the availability attribute with the
+platform corresponding to the target platform will be used; any others will be
+ignored.  If no availability attribute specifies availability for the current
+target platform, the availability attributes are ignored.  Supported platforms
+are:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">ios</span></tt></dt>
+<dd>Apple’s iOS operating system.  The minimum deployment target is specified by
+the <tt class="docutils literal"><span class="pre">-mios-version-min=*version*</span></tt> or <tt class="docutils literal"><span class="pre">-miphoneos-version-min=*version*</span></tt>
+command-line arguments.</dd>
+<dt><tt class="docutils literal"><span class="pre">macos</span></tt></dt>
+<dd>Apple’s Mac OS X operating system.  The minimum deployment target is
+specified by the <tt class="docutils literal"><span class="pre">-mmacosx-version-min=*version*</span></tt> command-line argument.
+<tt class="docutils literal"><span class="pre">macosx</span></tt> is supported for backward-compatibility reasons, but it is
+deprecated.</dd>
+<dt><tt class="docutils literal"><span class="pre">tvos</span></tt></dt>
+<dd>Apple’s tvOS operating system.  The minimum deployment target is specified by
+the <tt class="docutils literal"><span class="pre">-mtvos-version-min=*version*</span></tt> command-line argument.</dd>
+<dt><tt class="docutils literal"><span class="pre">watchos</span></tt></dt>
+<dd>Apple’s watchOS operating system.  The minimum deployment target is specified by
+the <tt class="docutils literal"><span class="pre">-mwatchos-version-min=*version*</span></tt> command-line argument.</dd>
+</dl>
+<p>A declaration can typically be used even when deploying back to a platform
+version prior to when the declaration was introduced.  When this happens, the
+declaration is <a class="reference external" href="https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html">weakly linked</a>,
+as if the <tt class="docutils literal"><span class="pre">weak_import</span></tt> attribute were added to the declaration.  A
+weakly-linked declaration may or may not be present a run-time, and a program
+can determine whether the declaration is present by checking whether the
+address of that declaration is non-NULL.</p>
+<p>The flag <tt class="docutils literal"><span class="pre">strict</span></tt> disallows using API when deploying back to a
+platform version prior to when the declaration was introduced.  An
+attempt to use such API before its introduction causes a hard error.
+Weakly-linking is almost always a better API choice, since it allows
+users to query availability at runtime.</p>
+<p>If there are multiple declarations of the same entity, the availability
+attributes must either match on a per-platform basis or later
+declarations must not have availability attributes for that
+platform. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span> <span class="c1">// okay, matches</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">ios</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">4.0</span><span class="p">)));</span> <span class="c1">// okay, adds a new platform</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span> <span class="c1">// okay, inherits both macos and ios availability from above.</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.5</span><span class="p">)));</span> <span class="c1">// error: mismatch</span>
+</pre></div>
+</div>
+<p>When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">A</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method2</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.4</span><span class="p">)));</span>
+<span class="k">@end</span>
+
+<span class="k">@interface</span> <span class="nc">B</span> : <span class="nc">A</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.3</span><span class="p">)));</span> <span class="c1">// okay: method moved into base class later</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span><span class="nf">method</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">availability</span><span class="p">(</span><span class="n">macos</span><span class="p">,</span><span class="n">introduced</span><span class="o">=</span><span class="mf">10.5</span><span class="p">)));</span> <span class="c1">// error: this method was available via the base class in 10.4</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="noreturn">
+<h3><a class="toc-backref" href="#id16">_Noreturn</a><a class="headerlink" href="#noreturn" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>A function declared as <tt class="docutils literal"><span class="pre">_Noreturn</span></tt> shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as <tt class="docutils literal"><span class="pre">_Noreturn</span></tt>
+that appears to be capable of returning to its caller.</p>
+</div>
+<div class="section" id="id2">
+<h3><a class="toc-backref" href="#id17">noreturn</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>A function declared as <tt class="docutils literal"><span class="pre">[[noreturn]]</span></tt> shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as <tt class="docutils literal"><span class="pre">[[noreturn]]</span></tt>
+that appears to be capable of returning to its caller.</p>
+</div>
+<div class="section" id="carries-dependency">
+<h3><a class="toc-backref" href="#id18">carries_dependency</a><a class="headerlink" href="#carries-dependency" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">carries_dependency</span></tt> attribute specifies dependency propagation into and
+out of functions.</p>
+<p>When specified on a function or Objective-C method, the <tt class="docutils literal"><span class="pre">carries_dependency</span></tt>
+attribute means that the return value carries a dependency out of the function,
+so that the implementation need not constrain ordering upon return from that
+function. Implementations of the function and its caller may choose to preserve
+dependencies instead of emitting memory ordering instructions such as fences.</p>
+<p>Note, this attribute does not change the meaning of the program, but may result
+in generation of more efficient code.</p>
+</div>
+<div class="section" id="convergent-clang-convergent">
+<h3><a class="toc-backref" href="#id19">convergent (clang::convergent)</a><a class="headerlink" href="#convergent-clang-convergent" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">convergent</span></tt> attribute can be placed on a function declaration. It is
+translated into the LLVM <tt class="docutils literal"><span class="pre">convergent</span></tt> attribute, which indicates that the call
+instructions of a function with this attribute cannot be made control-dependent
+on any additional values.</p>
+<p>In languages designed for SPMD/SIMT programming model, e.g. OpenCL or CUDA,
+the call instructions of a function with this attribute must be executed by
+all work items or threads in a work group or sub group.</p>
+<p>This attribute is different from <tt class="docutils literal"><span class="pre">noduplicate</span></tt> because it allows duplicating
+function calls if it can be proved that the duplicated function calls are
+not made control-dependent on any additional values, e.g., unrolling a loop
+executed by all work items.</p>
+<p>Sample usage:
+.. code-block:: c</p>
+<blockquote>
+<div>void convfunc(void) __attribute__((convergent));
+// Setting it as a C++11 attribute is also valid in a C++ program.
+// void convfunc(void) [[clang::convergent]];</div></blockquote>
+</div>
+<div class="section" id="deprecated-gnu-deprecated">
+<h3><a class="toc-backref" href="#id20">deprecated (gnu::deprecated)</a><a class="headerlink" href="#deprecated-gnu-deprecated" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">deprecated</span></tt> attribute can be applied to a function, a variable, or a
+type. This is useful when identifying functions, variables, or types that are
+expected to be removed in a future version of a program.</p>
+<p>Consider the function declaration for a hypothetical function <tt class="docutils literal"><span class="pre">f</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">deprecated</span><span class="p">(</span><span class="s">"message"</span><span class="p">,</span> <span class="s">"replacement"</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>When spelled as <cite>__attribute__((deprecated))</cite>, the deprecated attribute can have
+two optional string arguments. The first one is the message to display when
+emitting the warning; the second one enables the compiler to provide a Fix-It
+to replace the deprecated name with a new name. Otherwise, when spelled as
+<cite>[[gnu::deprecated]] or [[deprecated]]</cite>, the attribute can have one optional
+string argument which is the message to display when emitting the warning.</p>
+</div>
+<div class="section" id="diagnose-if">
+<h3><a class="toc-backref" href="#id21">diagnose_if</a><a class="headerlink" href="#diagnose-if" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> attribute can be placed on function declarations to emit
+warnings or errors at compile-time if calls to the attributed function meet
+certain user-defined criteria. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">abs</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="n">a</span> <span class="o">>=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">"Redundant abs call"</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="nf">must_abs</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="n">a</span> <span class="o">>=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">"Redundant abs call"</span><span class="p">,</span> <span class="s">"error"</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="n">val</span> <span class="o">=</span> <span class="n">abs</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// warning: Redundant abs call</span>
+<span class="kt">int</span> <span class="n">val2</span> <span class="o">=</span> <span class="n">must_abs</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> <span class="c1">// error: Redundant abs call</span>
+<span class="kt">int</span> <span class="n">val3</span> <span class="o">=</span> <span class="n">abs</span><span class="p">(</span><span class="n">val</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">val4</span> <span class="o">=</span> <span class="n">must_abs</span><span class="p">(</span><span class="n">val</span><span class="p">);</span> <span class="c1">// Because run-time checks are not emitted for</span>
+                          <span class="c1">// diagnose_if attributes, this executes without</span>
+                          <span class="c1">// issue.</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">diagnose_if</span></tt> is closely related to <tt class="docutils literal"><span class="pre">enable_if</span></tt>, with a few key differences:</p>
+<ul class="simple">
+<li>Overload resolution is not aware of <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> attributes: they’re
+considered only after we select the best candidate from a given candidate set.</li>
+<li>Function declarations that differ only in their <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> attributes are
+considered to be redeclarations of the same function (not overloads).</li>
+<li>If the condition provided to <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> cannot be evaluated, no
+diagnostic will be emitted.</li>
+</ul>
+<p>Otherwise, <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> is essentially the logical negation of <tt class="docutils literal"><span class="pre">enable_if</span></tt>.</p>
+<p>As a result of bullet number two, <tt class="docutils literal"><span class="pre">diagnose_if</span></tt> attributes will stack on the
+same function. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s">"diag1"</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s">"diag2"</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="n">bar</span> <span class="o">=</span> <span class="n">foo</span><span class="p">();</span> <span class="c1">// warning: diag1</span>
+                 <span class="c1">// warning: diag2</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">fooptr</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span> <span class="c1">// warning: diag1</span>
+                           <span class="c1">// warning: diag2</span>
+
+<span class="n">constexpr</span> <span class="kt">int</span> <span class="nf">supportsAPILevel</span><span class="p">(</span><span class="kt">int</span> <span class="n">N</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">N</span> <span class="o"><</span> <span class="mi">5</span><span class="p">;</span> <span class="p">}</span>
+<span class="kt">int</span> <span class="nf">baz</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="o">!</span><span class="n">supportsAPILevel</span><span class="p">(</span><span class="mi">10</span><span class="p">),</span>
+                             <span class="s">"Upgrade to API level 10 to use baz"</span><span class="p">,</span> <span class="s">"error"</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">baz</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">diagnose_if</span><span class="p">(</span><span class="o">!</span><span class="n">a</span><span class="p">,</span> <span class="s">"0 is not recommended."</span><span class="p">,</span> <span class="s">"warning"</span><span class="p">)));</span>
+
+<span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">bazptr</span><span class="p">)(</span><span class="kt">int</span><span class="p">)</span> <span class="o">=</span> <span class="n">baz</span><span class="p">;</span> <span class="c1">// error: Upgrade to API level 10 to use baz</span>
+<span class="kt">int</span> <span class="n">v</span> <span class="o">=</span> <span class="n">baz</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span> <span class="c1">// error: Upgrade to API level 10 to use baz</span>
+</pre></div>
+</div>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_attribute(diagnose_if)</span></tt>.</p>
+</div>
+<div class="section" id="disable-tail-calls-clang-disable-tail-calls">
+<h3><a class="toc-backref" href="#id22">disable_tail_calls (clang::disable_tail_calls)</a><a class="headerlink" href="#disable-tail-calls-clang-disable-tail-calls" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">disable_tail_calls</span></tt> attribute instructs the backend to not perform tail call optimization inside the marked function.</p>
+<p>For example:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">callee</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">disable_tail_calls</span><span class="p">))</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">callee</span><span class="p">(</span><span class="n">a</span><span class="p">);</span> <span class="c1">// This call is not tail-call optimized.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Marking virtual functions as <tt class="docutils literal"><span class="pre">disable_tail_calls</span></tt> is legal.</p>
+<blockquote>
+<div><div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">callee</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="k">class</span> <span class="nc">Base</span> <span class="p">{</span>
+<span class="nl">public:</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">disable_tail_calls</span><span class="p">]]</span> <span class="k">virtual</span> <span class="kt">int</span> <span class="n">foo1</span><span class="p">()</span> <span class="p">{</span>
+    <span class="k">return</span> <span class="n">callee</span><span class="p">();</span> <span class="c1">// This call is not tail-call optimized.</span>
+  <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Derived1</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Base</span> <span class="p">{</span>
+<span class="nl">public:</span>
+  <span class="kt">int</span> <span class="n">foo1</span><span class="p">()</span> <span class="n">override</span> <span class="p">{</span>
+    <span class="k">return</span> <span class="n">callee</span><span class="p">();</span> <span class="c1">// This call is tail-call optimized.</span>
+  <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="enable-if">
+<h3><a class="toc-backref" href="#id23">enable_if</a><a class="headerlink" href="#enable-if" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Some features of this attribute are experimental. The meaning of
+multiple enable_if attributes on a single declaration is subject to change in
+a future version of clang. Also, the ABI is not standardized and the name
+mangling may change in future versions. To avoid that, use asm labels.</p>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">enable_if</span></tt> attribute can be placed on function declarations to control
+which overload is selected based on the values of the function’s arguments.
+When combined with the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute, this feature is also
+available in C.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">isdigit</span><span class="p">(</span><span class="kt">int</span> <span class="n">c</span><span class="p">);</span>
+<span class="kt">int</span> <span class="nf">isdigit</span><span class="p">(</span><span class="kt">int</span> <span class="n">c</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">c</span> <span class="o"><=</span> <span class="o">-</span><span class="mi">1</span> <span class="o">||</span> <span class="n">c</span> <span class="o">></span> <span class="mi">255</span><span class="p">,</span> <span class="s">"chosen when 'c' is out of range"</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">unavailable</span><span class="p">(</span><span class="s">"'c' must have the value of an unsigned char or EOF"</span><span class="p">)));</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">char</span> <span class="n">c</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">isdigit</span><span class="p">(</span><span class="n">c</span><span class="p">);</span>
+  <span class="n">isdigit</span><span class="p">(</span><span class="mi">10</span><span class="p">);</span>
+  <span class="n">isdigit</span><span class="p">(</span><span class="o">-</span><span class="mi">10</span><span class="p">);</span>  <span class="c1">// results in a compile-time error.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The enable_if attribute takes two arguments, the first is an expression written
+in terms of the function parameters, the second is a string explaining why this
+overload candidate could not be selected to be displayed in diagnostics. The
+expression is part of the function signature for the purposes of determining
+whether it is a redeclaration (following the rules used when determining
+whether a C++ template specialization is ODR-equivalent), but is not part of
+the type.</p>
+<p>The enable_if expression is evaluated as if it were the body of a
+bool-returning constexpr function declared with the arguments of the function
+it is being applied to, then called with the parameters at the call site. If the
+result is false or could not be determined through constant expression
+evaluation, then this overload will not be chosen and the provided string may
+be used in a diagnostic if the compile fails as a result.</p>
+<p>Because the enable_if expression is an unevaluated context, there are no global
+state changes, nor the ability to pass information from the enable_if
+expression to the function body. For example, suppose we want calls to
+strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
+strbuf) only if the size of strbuf can be determined:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__attribute__</span><span class="p">((</span><span class="n">always_inline</span><span class="p">))</span>
+<span class="k">static</span> <span class="kr">inline</span> <span class="kt">size_t</span> <span class="n">strnlen</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">s</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">maxlen</span><span class="p">)</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span>
+  <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">!=</span> <span class="o">-</span><span class="mi">1</span><span class="p">))),</span>
+                           <span class="s">"chosen when the buffer size is known but 'maxlen' is not"</span><span class="p">)))</span>
+<span class="p">{</span>
+  <span class="k">return</span> <span class="n">strnlen_chk</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">maxlen</span><span class="p">,</span> <span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="mi">0</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Multiple enable_if attributes may be applied to a single declaration. In this
+case, the enable_if expressions are evaluated from left to right in the
+following manner. First, the candidates whose enable_if expressions evaluate to
+false or cannot be evaluated are discarded. If the remaining candidates do not
+share ODR-equivalent enable_if expressions, the overload resolution is
+ambiguous. Otherwise, enable_if overload resolution continues with the next
+enable_if attribute on the candidates that have not been discarded and have
+remaining enable_if attributes. In this way, we pick the most specific
+overload out of a number of viable overloads using enable_if.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>  <span class="c1">// #1</span>
+<span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>  <span class="c1">// #2</span>
+
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="kt">int</span> <span class="n">j</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>  <span class="c1">// #1</span>
+<span class="kt">void</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="kt">int</span> <span class="n">j</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">j</span><span class="p">,</span> <span class="s">""</span><span class="p">)))</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="nb">true</span><span class="p">)));</span>  <span class="c1">// #2</span>
+</pre></div>
+</div>
+<p>In this example, a call to f() is always resolved to #2, as the first enable_if
+expression is ODR-equivalent for both declarations, but #1 does not have another
+enable_if expression to continue evaluating, so the next round of evaluation has
+only a single candidate. In a call to g(1, 1), the call is ambiguous even though
+#2 has more enable_if attributes, because the first enable_if expressions are
+not ODR-equivalent.</p>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_attribute(enable_if)</span></tt>.</p>
+<p>Note that functions with one or more <tt class="docutils literal"><span class="pre">enable_if</span></tt> attributes may not have
+their address taken, unless all of the conditions specified by said
+<tt class="docutils literal"><span class="pre">enable_if</span></tt> are constants that evaluate to <tt class="docutils literal"><span class="pre">true</span></tt>. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">const</span> <span class="kt">int</span> <span class="n">TrueConstant</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+<span class="k">const</span> <span class="kt">int</span> <span class="n">FalseConstant</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="kt">int</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">a</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">||</span> <span class="n">a</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">h</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">i</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">TrueConstant</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">int</span> <span class="nf">j</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">FalseConstant</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+
+<span class="kt">void</span> <span class="nf">fn</span><span class="p">()</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">ptr</span><span class="p">)(</span><span class="kt">int</span><span class="p">);</span>
+  <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">f</span><span class="p">;</span> <span class="c1">// error: 'a > 0' is not always true</span>
+  <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">g</span><span class="p">;</span> <span class="c1">// error: 'a == 0 || a != 0' is not a truthy constant</span>
+  <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">h</span><span class="p">;</span> <span class="c1">// OK: 1 is a truthy constant</span>
+  <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">i</span><span class="p">;</span> <span class="c1">// OK: 'TrueConstant' is a truthy constant</span>
+  <span class="n">ptr</span> <span class="o">=</span> <span class="o">&</span><span class="n">j</span><span class="p">;</span> <span class="c1">// error: 'FalseConstant' is a constant, but not truthy</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Because <tt class="docutils literal"><span class="pre">enable_if</span></tt> evaluation happens during overload resolution,
+<tt class="docutils literal"><span class="pre">enable_if</span></tt> may give unintuitive results when used with templates, depending
+on when overloads are resolved. In the example below, clang will emit a
+diagnostic about no viable overloads for <tt class="docutils literal"><span class="pre">foo</span></tt> in <tt class="docutils literal"><span class="pre">bar</span></tt>, but not in <tt class="docutils literal"><span class="pre">baz</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">double</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">i</span> <span class="o">></span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">i</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">enable_if</span><span class="p">(</span><span class="n">i</span> <span class="o"><=</span> <span class="mi">0</span><span class="p">,</span> <span class="s">""</span><span class="p">)));</span>
+<span class="k">template</span> <span class="o"><</span><span class="kt">int</span> <span class="n">I</span><span class="o">></span>
+<span class="k">auto</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">foo</span><span class="p">(</span><span class="n">I</span><span class="p">);</span> <span class="p">}</span>
+
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span>
+<span class="k">auto</span> <span class="n">baz</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">foo</span><span class="p">(</span><span class="n">T</span><span class="o">::</span><span class="n">number</span><span class="p">);</span> <span class="p">}</span>
+
+<span class="k">struct</span> <span class="n">WithNumber</span> <span class="p">{</span> <span class="n">constexpr</span> <span class="k">static</span> <span class="kt">int</span> <span class="n">number</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span> <span class="p">};</span>
+<span class="kt">void</span> <span class="nf">callThem</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">bar</span><span class="o"><</span><span class="k">sizeof</span><span class="p">(</span><span class="n">WithNumber</span><span class="p">)</span><span class="o">></span><span class="p">();</span>
+  <span class="n">baz</span><span class="o"><</span><span class="n">WithNumber</span><span class="o">></span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This is because, in <tt class="docutils literal"><span class="pre">bar</span></tt>, <tt class="docutils literal"><span class="pre">foo</span></tt> is resolved prior to template
+instantiation, so the value for <tt class="docutils literal"><span class="pre">I</span></tt> isn’t known (thus, both <tt class="docutils literal"><span class="pre">enable_if</span></tt>
+conditions for <tt class="docutils literal"><span class="pre">foo</span></tt> fail). However, in <tt class="docutils literal"><span class="pre">baz</span></tt>, <tt class="docutils literal"><span class="pre">foo</span></tt> is resolved during
+template instantiation, so the value for <tt class="docutils literal"><span class="pre">T::number</span></tt> is known.</p>
+</div>
+<div class="section" id="flatten-gnu-flatten">
+<h3><a class="toc-backref" href="#id24">flatten (gnu::flatten)</a><a class="headerlink" href="#flatten-gnu-flatten" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">flatten</span></tt> attribute causes calls within the attributed function to
+be inlined unless it is impossible to do so, for example if the body of the
+callee is unavailable or if the callee has the <tt class="docutils literal"><span class="pre">noinline</span></tt> attribute.</p>
+</div>
+<div class="section" id="format-gnu-format">
+<h3><a class="toc-backref" href="#id25">format (gnu::format)</a><a class="headerlink" href="#format-gnu-format" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">format</span></tt> attribute, which indicates that the function
+accepts a <tt class="docutils literal"><span class="pre">printf</span></tt> or <tt class="docutils literal"><span class="pre">scanf</span></tt>-like format string and corresponding
+arguments or a <tt class="docutils literal"><span class="pre">va_list</span></tt> that contains these arguments.</p>
+<p>Please see <a class="reference external" href="http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html">GCC documentation about format attribute</a> to find details
+about attribute syntax.</p>
+<p>Clang implements two kinds of checks with this attribute.</p>
+<ol class="arabic">
+<li><p class="first">Clang checks that the function with the <tt class="docutils literal"><span class="pre">format</span></tt> attribute is called with
+a format string that uses format specifiers that are allowed, and that
+arguments match the format string.  This is the <tt class="docutils literal"><span class="pre">-Wformat</span></tt> warning, it is
+on by default.</p>
+</li>
+<li><p class="first">Clang checks that the format string argument is a literal string.  This is
+the <tt class="docutils literal"><span class="pre">-Wformat-nonliteral</span></tt> warning, it is off by default.</p>
+<p>Clang implements this mostly the same way as GCC, but there is a difference
+for functions that accept a <tt class="docutils literal"><span class="pre">va_list</span></tt> argument (for example, <tt class="docutils literal"><span class="pre">vprintf</span></tt>).
+GCC does not emit <tt class="docutils literal"><span class="pre">-Wformat-nonliteral</span></tt> warning for calls to such
+functions.  Clang does not warn if the format string comes from a function
+parameter, where the function is annotated with a compatible attribute,
+otherwise it warns.  For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__attribute__</span><span class="p">((</span><span class="n">__format__</span> <span class="p">(</span><span class="n">__scanf__</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">s</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="p">...)</span> <span class="p">{</span>
+  <span class="kt">va_list</span> <span class="n">ap</span><span class="p">;</span>
+  <span class="n">va_start</span><span class="p">(</span><span class="n">ap</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span>
+
+  <span class="n">vprintf</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">ap</span><span class="p">);</span> <span class="c1">// warning: format string is not a string literal</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case we warn because <tt class="docutils literal"><span class="pre">s</span></tt> contains a format string for a
+<tt class="docutils literal"><span class="pre">scanf</span></tt>-like function, but it is passed to a <tt class="docutils literal"><span class="pre">printf</span></tt>-like function.</p>
+<p>If the attribute is removed, clang still warns, because the format string is
+not a string literal.</p>
+<p>Another example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__attribute__</span><span class="p">((</span><span class="n">__format__</span> <span class="p">(</span><span class="n">__printf__</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">)))</span>
+<span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">s</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="p">...)</span> <span class="p">{</span>
+  <span class="kt">va_list</span> <span class="n">ap</span><span class="p">;</span>
+  <span class="n">va_start</span><span class="p">(</span><span class="n">ap</span><span class="p">,</span> <span class="n">buf</span><span class="p">);</span>
+
+  <span class="n">vprintf</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">ap</span><span class="p">);</span> <span class="c1">// warning</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this case Clang does not warn because the format string <tt class="docutils literal"><span class="pre">s</span></tt> and
+the corresponding arguments are annotated.  If the arguments are
+incorrect, the caller of <tt class="docutils literal"><span class="pre">foo</span></tt> will receive a warning.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="ifunc-gnu-ifunc">
+<h3><a class="toc-backref" href="#id26">ifunc (gnu::ifunc)</a><a class="headerlink" href="#ifunc-gnu-ifunc" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">__attribute__((ifunc("resolver")))</span></tt> is used to mark that the address of a declaration should be resolved at runtime by calling a resolver function.</p>
+<p>The symbol name of the resolver function is given in quotes.  A function with this name (after mangling) must be defined in the current translation unit; it may be <tt class="docutils literal"><span class="pre">static</span></tt>.  The resolver function should take no arguments and return a pointer.</p>
+<p>The <tt class="docutils literal"><span class="pre">ifunc</span></tt> attribute may only be used on a function declaration.  A function declaration with an <tt class="docutils literal"><span class="pre">ifunc</span></tt> attribute is considered to be a definition of the declared entity.  The entity must not have weak linkage; for example, in C++, it cannot be applied to a declaration if a definition at that location would be considered inline.</p>
+<p>Not all targets support this attribute.  ELF targets support this attribute when using binutils v2.20.1 or higher and glibc v2.11.1 or higher.  Non-ELF targets currently do not support this attribute.</p>
+</div>
+<div class="section" id="internal-linkage-clang-internal-linkage">
+<h3><a class="toc-backref" href="#id27">internal_linkage (clang::internal_linkage)</a><a class="headerlink" href="#internal-linkage-clang-internal-linkage" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">internal_linkage</span></tt> attribute changes the linkage type of the declaration to internal.
+This is similar to C-style <tt class="docutils literal"><span class="pre">static</span></tt>, but can be used on classes and class methods. When applied to a class definition,
+this attribute affects all methods and static data members of that class.
+This can be used to contain the ABI of a C++ library by excluding unwanted class methods from the export tables.</p>
+</div>
+<div class="section" id="id3">
+<h3><a class="toc-backref" href="#id28">interrupt</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((interrupt("ARGUMENT")))</span></tt> attribute on
+MIPS targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.</p>
+<p>By default, the compiler will produce a function prologue and epilogue suitable for
+an interrupt service routine that handles an External Interrupt Controller (eic)
+generated interrupt. This behaviour can be explicitly requested with the “eic”
+argument.</p>
+<p>Otherwise, for use with vectored interrupt mode, the argument passed should be
+of the form “vector=LEVEL” where LEVEL is one of the following values:
+“sw0”, “sw1”, “hw0”, “hw1”, “hw2”, “hw3”, “hw4”, “hw5”. The compiler will
+then set the interrupt mask to the corresponding level which will mask all
+interrupts up to and including the argument.</p>
+<p>The semantics are as follows:</p>
+<ul class="simple">
+<li>The prologue is modified so that the Exception Program Counter (EPC) and
+Status coprocessor registers are saved to the stack. The interrupt mask is
+set so that the function can only be interrupted by a higher priority
+interrupt. The epilogue will restore the previous values of EPC and Status.</li>
+<li>The prologue and epilogue are modified to save and restore all non-kernel
+registers as necessary.</li>
+<li>The FPU is disabled in the prologue, as the floating pointer registers are not
+spilled to the stack.</li>
+<li>The function return sequence is changed to use an exception return instruction.</li>
+<li>The parameter sets the interrupt mask for the function corresponding to the
+interrupt level specified. If no mask is specified the interrupt mask
+defaults to “eic”.</li>
+</ul>
+</div>
+<div class="section" id="noalias">
+<h3><a class="toc-backref" href="#id29">noalias</a><a class="headerlink" href="#noalias" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">noalias</span></tt> attribute indicates that the only memory accesses inside
+function are loads and stores from objects pointed to by its pointer-typed
+arguments, with arbitrary offsets.</p>
+</div>
+<div class="section" id="noduplicate-clang-noduplicate">
+<h3><a class="toc-backref" href="#id30">noduplicate (clang::noduplicate)</a><a class="headerlink" href="#noduplicate-clang-noduplicate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">noduplicate</span></tt> attribute can be placed on function declarations to control
+whether function calls to this function can be duplicated or not as a result of
+optimizations. This is required for the implementation of functions with
+certain special requirements, like the OpenCL “barrier” function, that might
+need to be run concurrently by all the threads that are executing in lockstep
+on the hardware. For example this attribute applied on the function
+“nodupfunc” in the code below avoids that:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">nodupfunc</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">noduplicate</span><span class="p">));</span>
+<span class="c1">// Setting it as a C++11 attribute is also valid</span>
+<span class="c1">// void nodupfunc() [[clang::noduplicate]];</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">();</span>
+<span class="kt">void</span> <span class="nf">bar</span><span class="p">();</span>
+
+<span class="n">nodupfunc</span><span class="p">();</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+  <span class="n">bar</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>gets possibly modified by some optimizations into code similar to this:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">a</span> <span class="o">></span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">nodupfunc</span><span class="p">();</span>
+  <span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+  <span class="n">nodupfunc</span><span class="p">();</span>
+  <span class="n">bar</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>where the call to “nodupfunc” is duplicated and sunk into the two branches
+of the condition.</p>
+</div>
+<div class="section" id="no-sanitize-clang-no-sanitize">
+<h3><a class="toc-backref" href="#id31">no_sanitize (clang::no_sanitize)</a><a class="headerlink" href="#no-sanitize-clang-no-sanitize" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use the <tt class="docutils literal"><span class="pre">no_sanitize</span></tt> attribute on a function declaration to specify
+that a particular instrumentation or set of instrumentations should not be
+applied to that function. The attribute takes a list of string literals,
+which have the same meaning as values accepted by the <tt class="docutils literal"><span class="pre">-fno-sanitize=</span></tt>
+flag. For example, <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("address",</span> <span class="pre">"thread")))</span></tt>
+specifies that AddressSanitizer and ThreadSanitizer should not be applied
+to the function.</p>
+<p>See <a class="reference internal" href="UsersManual.html#controlling-code-generation"><em>Controlling Code Generation</em></a> for a
+full list of supported sanitizer flags.</p>
+</div>
+<div class="section" id="no-sanitize-address-no-address-safety-analysis-gnu-no-address-safety-analysis-gnu-no-sanitize-address">
+<h3><a class="toc-backref" href="#id32">no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)</a><a class="headerlink" href="#no-sanitize-address-no-address-safety-analysis-gnu-no-address-safety-analysis-gnu-no-sanitize-address" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p id="langext-address-sanitizer">Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_address))</span></tt> on a function declaration to
+specify that address safety instrumentation (e.g. AddressSanitizer) should
+not be applied to that function.</p>
+</div>
+<div class="section" id="no-sanitize-thread">
+<h3><a class="toc-backref" href="#id33">no_sanitize_thread</a><a class="headerlink" href="#no-sanitize-thread" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p id="langext-thread-sanitizer">Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_thread))</span></tt> on a function declaration to
+specify that checks for data races on plain (non-atomic) memory accesses should
+not be inserted by ThreadSanitizer. The function is still instrumented by the
+tool to avoid false positives and provide meaningful stack traces.</p>
+</div>
+<div class="section" id="no-sanitize-memory">
+<h3><a class="toc-backref" href="#id34">no_sanitize_memory</a><a class="headerlink" href="#no-sanitize-memory" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p id="langext-memory-sanitizer">Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_memory))</span></tt> on a function declaration to
+specify that checks for uninitialized memory should not be inserted
+(e.g. by MemorySanitizer). The function may still be instrumented by the tool
+to avoid false positives in other places.</p>
+</div>
+<div class="section" id="no-split-stack-gnu-no-split-stack">
+<h3><a class="toc-backref" href="#id35">no_split_stack (gnu::no_split_stack)</a><a class="headerlink" href="#no-split-stack-gnu-no-split-stack" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">no_split_stack</span></tt> attribute disables the emission of the split stack
+preamble for a particular function. It has no effect if <tt class="docutils literal"><span class="pre">-fsplit-stack</span></tt>
+is not specified.</p>
+</div>
+<div class="section" id="not-tail-called-clang-not-tail-called">
+<h3><a class="toc-backref" href="#id36">not_tail_called (clang::not_tail_called)</a><a class="headerlink" href="#not-tail-called-clang-not-tail-called" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">not_tail_called</span></tt> attribute prevents tail-call optimization on statically bound calls. It has no effect on indirect calls. Virtual functions, objective-c methods, and functions marked as <tt class="docutils literal"><span class="pre">always_inline</span></tt> cannot be marked as <tt class="docutils literal"><span class="pre">not_tail_called</span></tt>.</p>
+<p>For example, it prevents tail-call optimization in the following case:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">not_tail_called</span><span class="p">))</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">foo1</span><span class="p">(</span><span class="n">a</span><span class="p">);</span> <span class="c1">// No tail-call optimization on direct calls.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>However, it doesn’t prevent tail-call optimization in this case:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">not_tail_called</span><span class="p">))</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">int</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">fn</span><span class="p">)(</span><span class="kt">int</span><span class="p">)</span> <span class="o">=</span> <span class="o">&</span><span class="n">foo1</span><span class="p">;</span>
+
+  <span class="c1">// not_tail_called has no effect on an indirect call even if the call can be</span>
+  <span class="c1">// resolved at compile time.</span>
+  <span class="k">return</span> <span class="p">(</span><span class="o">*</span><span class="n">fn</span><span class="p">)(</span><span class="n">a</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Marking virtual functions as <tt class="docutils literal"><span class="pre">not_tail_called</span></tt> is an error:</p>
+<blockquote>
+<div><div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Base</span> <span class="p">{</span>
+<span class="nl">public:</span>
+  <span class="c1">// not_tail_called on a virtual function is an error.</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">not_tail_called</span><span class="p">]]</span> <span class="k">virtual</span> <span class="kt">int</span> <span class="n">foo1</span><span class="p">();</span>
+
+  <span class="k">virtual</span> <span class="kt">int</span> <span class="nf">foo2</span><span class="p">();</span>
+
+  <span class="c1">// Non-virtual functions can be marked ``not_tail_called``.</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">not_tail_called</span><span class="p">]]</span> <span class="kt">int</span> <span class="n">foo3</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Derived1</span> <span class="o">:</span> <span class="k">public</span> <span class="n">Base</span> <span class="p">{</span>
+<span class="nl">public:</span>
+  <span class="kt">int</span> <span class="n">foo1</span><span class="p">()</span> <span class="n">override</span><span class="p">;</span>
+
+  <span class="c1">// not_tail_called on a virtual function is an error.</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">not_tail_called</span><span class="p">]]</span> <span class="kt">int</span> <span class="n">foo2</span><span class="p">()</span> <span class="n">override</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="pragma-omp-declare-simd">
+<h3><a class="toc-backref" href="#id37">#pragma omp declare simd</a><a class="headerlink" href="#pragma-omp-declare-simd" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <cite>declare simd</cite> construct can be applied to a function to enable the creation
+of one or more versions that can process multiple arguments using SIMD
+instructions from a single invocation in a SIMD loop. The <cite>declare simd</cite>
+directive is a declarative directive. There may be multiple <cite>declare simd</cite>
+directives for a function. The use of a <cite>declare simd</cite> construct on a function
+enables the creation of SIMD versions of the associated function that can be
+used to process multiple arguments from a single invocation from a SIMD loop
+concurrently.
+The syntax of the <cite>declare simd</cite> construct is as follows:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre>
+</pre></div>
+</div>
+<p>#pragma omp declare simd [clause[[,] clause] ...] new-line
+[#pragma omp declare simd [clause[[,] clause] ...] new-line]
+[...]
+function definition or declaration</p>
+</div></blockquote>
+<p>where clause is one of the following:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre>
+</pre></div>
+</div>
+<p>simdlen(length)
+linear(argument-list[:constant-linear-step])
+aligned(argument-list[:alignment])
+uniform(argument-list)
+inbranch
+notinbranch</p>
+</div></blockquote>
+</div>
+<div class="section" id="pragma-omp-declare-target">
+<h3><a class="toc-backref" href="#id38">#pragma omp declare target</a><a class="headerlink" href="#pragma-omp-declare-target" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <cite>declare target</cite> directive specifies that variables and functions are mapped
+to a device for OpenMP offload mechanism.</p>
+<p>The syntax of the declare target directive is as follows:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre>
+</pre></div>
+</div>
+<p>#pragma omp declare target new-line
+declarations-definition-seq
+#pragma omp end declare target new-line</p>
+</div></blockquote>
+</div>
+<div class="section" id="objc-boxable">
+<h3><a class="toc-backref" href="#id39">objc_boxable</a><a class="headerlink" href="#objc-boxable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Structs and unions marked with the <tt class="docutils literal"><span class="pre">objc_boxable</span></tt> attribute can be used
+with the Objective-C boxed expression syntax, <tt class="docutils literal"><span class="pre">@(...)</span></tt>.</p>
+<p><strong>Usage</strong>: <tt class="docutils literal"><span class="pre">__attribute__((objc_boxable))</span></tt>. This attribute
+can only be placed on a declaration of a trivially-copyable struct or union:</p>
+<div class="highlight-objc"><div class="highlight"><pre>struct __attribute__((objc_boxable)) some_struct {
+  int i;
+};
+union __attribute__((objc_boxable)) some_union {
+  int i;
+  float f;
+};
+typedef struct __attribute__((objc_boxable)) _some_struct some_struct;
+
+// ...
+
+some_struct ss;
+NSValue *boxed = @(ss);
+</pre></div>
+</div>
+</div>
+<div class="section" id="objc-method-family">
+<h3><a class="toc-backref" href="#id40">objc_method_family</a><a class="headerlink" href="#objc-method-family" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Many methods in Objective-C have conventional meanings determined by their
+selectors. It is sometimes useful to be able to mark a method as having a
+particular conventional meaning despite not having the right selector, or as
+not having the conventional meaning that its selector would suggest. For these
+use cases, we provide an attribute to specifically describe the “method family”
+that a method belongs to.</p>
+<p><strong>Usage</strong>: <tt class="docutils literal"><span class="pre">__attribute__((objc_method_family(X)))</span></tt>, where <tt class="docutils literal"><span class="pre">X</span></tt> is one of
+<tt class="docutils literal"><span class="pre">none</span></tt>, <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">init</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, or <tt class="docutils literal"><span class="pre">new</span></tt>.  This
+attribute can only be placed at the end of a method declaration:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">-</span> <span class="p">(</span><span class="n">NSString</span> <span class="o">*</span><span class="p">)</span><span class="nf">initMyStringValue</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_method_family</span><span class="p">(</span><span class="n">none</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>Users who do not wish to change the conventional meaning of a method, and who
+merely want to document its non-standard retain and release semantics, should
+use the retaining behavior attributes (<tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt>,
+<tt class="docutils literal"><span class="pre">ns_returns_not_retained</span></tt>, etc).</p>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_attribute(objc_method_family)</span></tt>.</p>
+</div>
+<div class="section" id="objc-requires-super">
+<h3><a class="toc-backref" href="#id41">objc_requires_super</a><a class="headerlink" href="#objc-requires-super" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Some Objective-C classes allow a subclass to override a particular method in a
+parent class but expect that the overriding method also calls the overridden
+method in the parent class. For these cases, we provide an attribute to
+designate that a method requires a “call to <tt class="docutils literal"><span class="pre">super</span></tt>” in the overriding
+method in the subclass.</p>
+<p><strong>Usage</strong>: <tt class="docutils literal"><span class="pre">__attribute__((objc_requires_super))</span></tt>.  This attribute can only
+be placed at the end of a method declaration:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">foo</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_requires_super</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This attribute can only be applied the method declarations within a class, and
+not a protocol.  Currently this attribute does not enforce any placement of
+where the call occurs in the overriding method (such as in the case of
+<tt class="docutils literal"><span class="pre">-dealloc</span></tt> where the call must appear at the end).  It checks only that it
+exists.</p>
+<p>Note that on both OS X and iOS that the Foundation framework provides a
+convenience macro <tt class="docutils literal"><span class="pre">NS_REQUIRES_SUPER</span></tt> that provides syntactic sugar for this
+attribute:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">foo</span> <span class="n">NS_REQUIRES_SUPER</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This macro is conditionally defined depending on the compiler’s support for
+this attribute.  If the compiler does not support the attribute the macro
+expands to nothing.</p>
+<p>Operationally, when a method has this annotation the compiler will warn if the
+implementation of an override in a subclass does not call super.  For example:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="nl">warning:</span> <span class="n">method</span> <span class="n">possibly</span> <span class="n">missing</span> <span class="n">a</span> <span class="p">[</span><span class="n">super</span> <span class="n">AnnotMeth</span><span class="p">]</span> <span class="n">call</span>
+<span class="o">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">AnnotMeth</span><span class="p">{};</span>
+                   <span class="o">^</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="objc-runtime-name">
+<h3><a class="toc-backref" href="#id42">objc_runtime_name</a><a class="headerlink" href="#objc-runtime-name" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>By default, the Objective-C interface or protocol identifier is used
+in the metadata name for that object. The <cite>objc_runtime_name</cite>
+attribute allows annotated interfaces or protocols to use the
+specified string argument in the object’s metadata name instead of the
+default name.</p>
+<p><strong>Usage</strong>: <tt class="docutils literal"><span class="pre">__attribute__((objc_runtime_name("MyLocalName")))</span></tt>.  This attribute
+can only be placed before an @protocol or @interface declaration:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="n">__attribute__</span><span class="p">((</span><span class="n">objc_runtime_name</span><span class="p">(</span><span class="s">"MyLocalName"</span><span class="p">)))</span>
+<span class="k">@interface</span> <span class="nc">Message</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="objc-runtime-visible">
+<h3><a class="toc-backref" href="#id43">objc_runtime_visible</a><a class="headerlink" href="#objc-runtime-visible" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies that the Objective-C class to which it applies is visible to the Objective-C runtime but not to the linker. Classes annotated with this attribute cannot be subclassed and cannot have categories defined for them.</p>
+</div>
+<div class="section" id="optnone-clang-optnone">
+<h3><a class="toc-backref" href="#id44">optnone (clang::optnone)</a><a class="headerlink" href="#optnone-clang-optnone" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">optnone</span></tt> attribute suppresses essentially all optimizations
+on a function or method, regardless of the optimization level applied to
+the compilation unit as a whole.  This is particularly useful when you
+need to debug a particular function, but it is infeasible to build the
+entire application without optimization.  Avoiding optimization on the
+specified function can improve the quality of the debugging information
+for that function.</p>
+<p>This attribute is incompatible with the <tt class="docutils literal"><span class="pre">always_inline</span></tt> and <tt class="docutils literal"><span class="pre">minsize</span></tt>
+attributes.</p>
+</div>
+<div class="section" id="overloadable">
+<h3><a class="toc-backref" href="#id45">overloadable</a><a class="headerlink" href="#overloadable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang provides support for C++ function overloading in C.  Function overloading
+in C is introduced using the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute.  For example, one
+might provide several overloaded versions of a <tt class="docutils literal"><span class="pre">tgsin</span></tt> function that invokes
+the appropriate standard function computing the sine of a value with <tt class="docutils literal"><span class="pre">float</span></tt>,
+<tt class="docutils literal"><span class="pre">double</span></tt>, or <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span></tt> precision:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include <math.h></span>
+<span class="kt">float</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sinf</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="kt">double</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">double</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sin</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="kt">long</span> <span class="kt">double</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">))</span> <span class="n">tgsin</span><span class="p">(</span><span class="kt">long</span> <span class="kt">double</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">sinl</span><span class="p">(</span><span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Given these declarations, one can call <tt class="docutils literal"><span class="pre">tgsin</span></tt> with a <tt class="docutils literal"><span class="pre">float</span></tt> value to
+receive a <tt class="docutils literal"><span class="pre">float</span></tt> result, with a <tt class="docutils literal"><span class="pre">double</span></tt> to receive a <tt class="docutils literal"><span class="pre">double</span></tt> result,
+etc.  Function overloading in C follows the rules of C++ function overloading
+to pick the best overload given the call arguments, with a few C-specific
+semantics:</p>
+<ul class="simple">
+<li>Conversion from <tt class="docutils literal"><span class="pre">float</span></tt> or <tt class="docutils literal"><span class="pre">double</span></tt> to <tt class="docutils literal"><span class="pre">long</span> <span class="pre">double</span></tt> is ranked as a
+floating-point promotion (per C99) rather than as a floating-point conversion
+(as in C++).</li>
+<li>A conversion from a pointer of type <tt class="docutils literal"><span class="pre">T*</span></tt> to a pointer of type <tt class="docutils literal"><span class="pre">U*</span></tt> is
+considered a pointer conversion (with conversion rank) if <tt class="docutils literal"><span class="pre">T</span></tt> and <tt class="docutils literal"><span class="pre">U</span></tt> are
+compatible types.</li>
+<li>A conversion from type <tt class="docutils literal"><span class="pre">T</span></tt> to a value of type <tt class="docutils literal"><span class="pre">U</span></tt> is permitted if <tt class="docutils literal"><span class="pre">T</span></tt>
+and <tt class="docutils literal"><span class="pre">U</span></tt> are compatible types.  This conversion is given “conversion” rank.</li>
+<li>If no viable candidates are otherwise available, we allow a conversion from a
+pointer of type <tt class="docutils literal"><span class="pre">T*</span></tt> to a pointer of type <tt class="docutils literal"><span class="pre">U*</span></tt>, where <tt class="docutils literal"><span class="pre">T</span></tt> and <tt class="docutils literal"><span class="pre">U</span></tt> are
+incompatible. This conversion is ranked below all other types of conversions.
+Please note: <tt class="docutils literal"><span class="pre">U</span></tt> lacking qualifiers that are present on <tt class="docutils literal"><span class="pre">T</span></tt> is sufficient
+for <tt class="docutils literal"><span class="pre">T</span></tt> and <tt class="docutils literal"><span class="pre">U</span></tt> to be incompatible.</li>
+</ul>
+<p>The declaration of <tt class="docutils literal"><span class="pre">overloadable</span></tt> functions is restricted to function
+declarations and definitions.  Most importantly, if any function with a given
+name is given the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute, then all function declarations
+and definitions with that name (and in that scope) must have the
+<tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute.  This rule even applies to redeclarations of
+functions whose original declaration had the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute, e.g.,</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span>
+<span class="kt">float</span> <span class="nf">f</span><span class="p">(</span><span class="kt">float</span><span class="p">);</span> <span class="c1">// error: declaration of "f" must have the "overloadable" attribute</span>
+
+<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span>
+<span class="kt">int</span> <span class="nf">g</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span> <span class="c1">// error: redeclaration of "g" must also have the "overloadable" attribute</span>
+</pre></div>
+</div>
+<p>Functions marked <tt class="docutils literal"><span class="pre">overloadable</span></tt> must have prototypes.  Therefore, the
+following code is ill-formed:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">h</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">));</span> <span class="c1">// error: h does not have a prototype</span>
+</pre></div>
+</div>
+<p>However, <tt class="docutils literal"><span class="pre">overloadable</span></tt> functions are allowed to use a ellipsis even if there
+are no named parameters (as is permitted in C++).  This feature is particularly
+useful when combined with the <tt class="docutils literal"><span class="pre">unavailable</span></tt> attribute:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">honeypot</span><span class="p">(...)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">overloadable</span><span class="p">,</span> <span class="n">unavailable</span><span class="p">));</span> <span class="c1">// calling me is an error</span>
+</pre></div>
+</div>
+<p>Functions declared with the <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute have their names mangled
+according to the same rules as C++ function names.  For example, the three
+<tt class="docutils literal"><span class="pre">tgsin</span></tt> functions in our motivating example get the mangled names
+<tt class="docutils literal"><span class="pre">_Z5tgsinf</span></tt>, <tt class="docutils literal"><span class="pre">_Z5tgsind</span></tt>, and <tt class="docutils literal"><span class="pre">_Z5tgsine</span></tt>, respectively.  There are two
+caveats to this use of name mangling:</p>
+<ul class="simple">
+<li>Future versions of Clang may change the name mangling of functions overloaded
+in C, so you should not depend on an specific mangling.  To be completely
+safe, we strongly urge the use of <tt class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></tt> with <tt class="docutils literal"><span class="pre">overloadable</span></tt>
+functions.</li>
+<li>The <tt class="docutils literal"><span class="pre">overloadable</span></tt> attribute has almost no meaning when used in C++,
+because names will already be mangled and functions are already overloadable.
+However, when an <tt class="docutils literal"><span class="pre">overloadable</span></tt> function occurs within an <tt class="docutils literal"><span class="pre">extern</span> <span class="pre">"C"</span></tt>
+linkage specification, it’s name <em>will</em> be mangled in the same way as it
+would in C.</li>
+</ul>
+<p>Query for this feature with <tt class="docutils literal"><span class="pre">__has_extension(attribute_overloadable)</span></tt>.</p>
+</div>
+<div class="section" id="release-capability-release-shared-capability-clang-release-capability-clang-release-shared-capability">
+<h3><a class="toc-backref" href="#id46">release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)</a><a class="headerlink" href="#release-capability-release-shared-capability-clang-release-capability-clang-release-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function as releasing a capability.</p>
+</div>
+<div class="section" id="kernel">
+<h3><a class="toc-backref" href="#id47">kernel</a><a class="headerlink" href="#kernel" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">__attribute__((kernel))</span></tt> is used to mark a <tt class="docutils literal"><span class="pre">kernel</span></tt> function in
+RenderScript.</p>
+<p>In RenderScript, <tt class="docutils literal"><span class="pre">kernel</span></tt> functions are used to express data-parallel
+computations.  The RenderScript runtime efficiently parallelizes <tt class="docutils literal"><span class="pre">kernel</span></tt>
+functions to run on computational resources such as multi-core CPUs and GPUs.
+See the <a class="reference external" href="https://developer.android.com/guide/topics/renderscript/compute.html">RenderScript</a> documentation for more information.</p>
+</div>
+<div class="section" id="target-gnu-target">
+<h3><a class="toc-backref" href="#id48">target (gnu::target)</a><a class="headerlink" href="#target-gnu-target" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the GNU style <tt class="docutils literal"><span class="pre">__attribute__((target("OPTIONS")))</span></tt> attribute.
+This attribute may be attached to a function definition and instructs
+the backend to use different code generation options than were passed on the
+command line.</p>
+<p>The current set of options correspond to the existing “subtarget features” for
+the target with or without a “-mno-” in front corresponding to the absence
+of the feature, as well as <tt class="docutils literal"><span class="pre">arch="CPU"</span></tt> which will change the default “CPU”
+for the function.</p>
+<p>Example “subtarget features” from the x86 backend include: “mmx”, “sse”, “sse4.2”,
+“avx”, “xop” and largely correspond to the machine specific options handled by
+the front end.</p>
+</div>
+<div class="section" id="try-acquire-capability-try-acquire-shared-capability-clang-try-acquire-capability-clang-try-acquire-shared-capability">
+<h3><a class="toc-backref" href="#id49">try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)</a><a class="headerlink" href="#try-acquire-capability-try-acquire-shared-capability-clang-try-acquire-capability-clang-try-acquire-shared-capability" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Marks a function that attempts to acquire a capability. This function may fail to
+actually acquire the capability; they accept a Boolean value determining
+whether acquiring the capability means success (true), or failing to acquire
+the capability means success (false).</p>
+</div>
+<div class="section" id="nodiscard-warn-unused-result-clang-warn-unused-result-gnu-warn-unused-result">
+<h3><a class="toc-backref" href="#id50">nodiscard, warn_unused_result, clang::warn_unused_result, gnu::warn_unused_result</a><a class="headerlink" href="#nodiscard-warn-unused-result-clang-warn-unused-result-gnu-warn-unused-result" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the ability to diagnose when the results of a function call
+expression are discarded under suspicious circumstances. A diagnostic is
+generated when a function or its return type is marked with <tt class="docutils literal"><span class="pre">[[nodiscard]]</span></tt>
+(or <tt class="docutils literal"><span class="pre">__attribute__((warn_unused_result))</span></tt>) and the function call appears as a
+potentially-evaluated discarded-value expression that is not explicitly cast to
+<cite>void</cite>.</p>
+</div>
+<div class="section" id="xray-always-instrument-clang-xray-always-instrument-xray-never-instrument-clang-xray-never-instrument">
+<h3><a class="toc-backref" href="#id51">xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument)</a><a class="headerlink" href="#xray-always-instrument-clang-xray-always-instrument-xray-never-instrument-clang-xray-never-instrument" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">__attribute__((xray_always_instrument))</span></tt> or <tt class="docutils literal"><span class="pre">[[clang::xray_always_instrument]]</span></tt> is used to mark member functions (in C++), methods (in Objective C), and free functions (in C, C++, and Objective C) to be instrumented with XRay. This will cause the function to always have space at the beginning and exit points to allow for runtime patching.</p>
+<p>Conversely, <tt class="docutils literal"><span class="pre">__attribute__((xray_never_instrument))</span></tt> or <tt class="docutils literal"><span class="pre">[[clang::xray_never_instrument]]</span></tt> will inhibit the insertion of these instrumentation points.</p>
+<p>If a function has neither of these attributes, they become subject to the XRay heuristics used to determine whether a function should be instrumented or otherwise.</p>
+</div>
+</div>
+<div class="section" id="variable-attributes">
+<h2><a class="toc-backref" href="#id52">Variable Attributes</a><a class="headerlink" href="#variable-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="dllexport-gnu-dllexport">
+<h3><a class="toc-backref" href="#id53">dllexport (gnu::dllexport)</a><a class="headerlink" href="#dllexport-gnu-dllexport" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> attribute declares a variable, function, or
+Objective-C interface to be exported from the module.  It is available under the
+<tt class="docutils literal"><span class="pre">-fdeclspec</span></tt> flag for compatibility with various compilers.  The primary use
+is for COFF object files which explicitly specify what interfaces are available
+for external use.  See the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx">dllexport</a> documentation on MSDN for more
+information.</p>
+</div>
+<div class="section" id="dllimport-gnu-dllimport">
+<h3><a class="toc-backref" href="#id54">dllimport (gnu::dllimport)</a><a class="headerlink" href="#dllimport-gnu-dllimport" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">__declspec(dllimport)</span></tt> attribute declares a variable, function, or
+Objective-C interface to be imported from an external module.  It is available
+under the <tt class="docutils literal"><span class="pre">-fdeclspec</span></tt> flag for compatibility with various compilers.  The
+primary use is for COFF object files which explicitly specify what interfaces
+are imported from external modules.  See the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx">dllimport</a> documentation on MSDN
+for more information.</p>
+</div>
+<div class="section" id="init-seg">
+<h3><a class="toc-backref" href="#id55">init_seg</a><a class="headerlink" href="#init-seg" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The attribute applied by <tt class="docutils literal"><span class="pre">pragma</span> <span class="pre">init_seg()</span></tt> controls the section into
+which global initialization function pointers are emitted.  It is only
+available with <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt>.  Typically, this function pointer is
+emitted into <tt class="docutils literal"><span class="pre">.CRT$XCU</span></tt> on Windows.  The user can change the order of
+initialization by using a different section name with the same
+<tt class="docutils literal"><span class="pre">.CRT$XC</span></tt> prefix and a suffix that sorts lexicographically before or
+after the standard <tt class="docutils literal"><span class="pre">.CRT$XCU</span></tt> sections.  See the <a class="reference external" href="http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx">init_seg</a>
+documentation on MSDN for more information.</p>
+</div>
+<div class="section" id="nodebug-gnu-nodebug">
+<h3><a class="toc-backref" href="#id56">nodebug (gnu::nodebug)</a><a class="headerlink" href="#nodebug-gnu-nodebug" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">nodebug</span></tt> attribute allows you to suppress debugging information for a
+function or method, or for a variable that is not a parameter or a non-static
+data member.</p>
+</div>
+<div class="section" id="nosvm">
+<h3><a class="toc-backref" href="#id57">nosvm</a><a class="headerlink" href="#nosvm" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>OpenCL 2.0 supports the optional <tt class="docutils literal"><span class="pre">__attribute__((nosvm))</span></tt> qualifier for
+pointer variable. It informs the compiler that the pointer does not refer
+to a shared virtual memory region. See OpenCL v2.0 s6.7.2 for details.</p>
+<p>Since it is not widely used and has been removed from OpenCL 2.1, it is ignored
+by Clang.</p>
+</div>
+<div class="section" id="pass-object-size">
+<h3><a class="toc-backref" href="#id58">pass_object_size</a><a class="headerlink" href="#pass-object-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The mangling of functions with parameters that are annotated with
+<tt class="docutils literal"><span class="pre">pass_object_size</span></tt> is subject to change. You can get around this by
+using <tt class="docutils literal"><span class="pre">__asm__("foo")</span></tt> to explicitly name your functions, thus preserving
+your ABI; also, non-overloadable C functions with <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> are
+not mangled.</p>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">pass_object_size(Type)</span></tt> attribute can be placed on function parameters to
+instruct clang to call <tt class="docutils literal"><span class="pre">__builtin_object_size(param,</span> <span class="pre">Type)</span></tt> at each callsite
+of said function, and implicitly pass the result of this call in as an invisible
+argument of type <tt class="docutils literal"><span class="pre">size_t</span></tt> directly after the parameter annotated with
+<tt class="docutils literal"><span class="pre">pass_object_size</span></tt>. Clang will also replace any calls to
+<tt class="docutils literal"><span class="pre">__builtin_object_size(param,</span> <span class="pre">Type)</span></tt> in the function by said implicit
+parameter.</p>
+<p>Example usage:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">bzero1</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="k">const</span> <span class="n">p</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">pass_object_size</span><span class="p">(</span><span class="mi">0</span><span class="p">))))</span>
+    <span class="n">__attribute__</span><span class="p">((</span><span class="n">noinline</span><span class="p">))</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+  <span class="k">for</span> <span class="p">(</span><span class="cm">/**/</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="n">__builtin_object_size</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">p</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+  <span class="p">}</span>
+  <span class="k">return</span> <span class="n">i</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+  <span class="kt">char</span> <span class="n">chars</span><span class="p">[</span><span class="mi">100</span><span class="p">];</span>
+  <span class="kt">int</span> <span class="n">n</span> <span class="o">=</span> <span class="n">bzero1</span><span class="p">(</span><span class="o">&</span><span class="n">chars</span><span class="p">[</span><span class="mi">0</span><span class="p">]);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">n</span> <span class="o">==</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">chars</span><span class="p">));</span>
+  <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If successfully evaluating <tt class="docutils literal"><span class="pre">__builtin_object_size(param,</span> <span class="pre">Type)</span></tt> at the
+callsite is not possible, then the “failed” value is passed in. So, using the
+definition of <tt class="docutils literal"><span class="pre">bzero1</span></tt> from above, the following code would exit cleanly:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main2</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[])</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">n</span> <span class="o">=</span> <span class="n">bzero1</span><span class="p">(</span><span class="n">argv</span><span class="p">);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">n</span> <span class="o">==</span> <span class="o">-</span><span class="mi">1</span><span class="p">);</span>
+  <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">pass_object_size</span></tt> plays a part in overload resolution. If two overload
+candidates are otherwise equally good, then the overload with one or more
+parameters with <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> is preferred. This implies that the choice
+between two identical overloads both with <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> on one or more
+parameters will always be ambiguous; for this reason, having two such overloads
+is illegal. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define PS(N) __attribute__((pass_object_size(N)))</span>
+<span class="c1">// OK</span>
+<span class="kt">void</span> <span class="nf">Foo</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">a</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">b</span><span class="p">);</span> <span class="c1">// Overload A</span>
+<span class="c1">// OK -- overload A has no parameters with pass_object_size.</span>
+<span class="kt">void</span> <span class="nf">Foo</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">a</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> <span class="kt">char</span> <span class="o">*</span><span class="n">b</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span> <span class="c1">// Overload B</span>
+<span class="c1">// Error -- Same signature (sans pass_object_size) as overload B, and both</span>
+<span class="c1">// overloads have one or more parameters with the pass_object_size attribute.</span>
+<span class="kt">void</span> <span class="nf">Foo</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">a</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> <span class="kt">void</span> <span class="o">*</span><span class="n">b</span><span class="p">);</span>
+
+<span class="c1">// OK</span>
+<span class="kt">void</span> <span class="nf">Bar</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">a</span> <span class="n">PS</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span> <span class="c1">// Overload C</span>
+<span class="c1">// OK</span>
+<span class="kt">void</span> <span class="nf">Bar</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="n">c</span> <span class="n">PS</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span> <span class="c1">// Overload D</span>
+
+<span class="kt">void</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+  <span class="kt">char</span> <span class="n">known</span><span class="p">[</span><span class="mi">10</span><span class="p">],</span> <span class="o">*</span><span class="n">unknown</span><span class="p">;</span>
+  <span class="n">Foo</span><span class="p">(</span><span class="n">unknown</span><span class="p">,</span> <span class="n">unknown</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+  <span class="n">Foo</span><span class="p">(</span><span class="n">known</span><span class="p">,</span> <span class="n">unknown</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+  <span class="n">Foo</span><span class="p">(</span><span class="n">unknown</span><span class="p">,</span> <span class="n">known</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+  <span class="n">Foo</span><span class="p">(</span><span class="n">known</span><span class="p">,</span> <span class="n">known</span><span class="p">);</span> <span class="c1">// Calls overload B</span>
+
+  <span class="n">Bar</span><span class="p">(</span><span class="n">known</span><span class="p">);</span> <span class="c1">// Calls overload D</span>
+  <span class="n">Bar</span><span class="p">(</span><span class="n">unknown</span><span class="p">);</span> <span class="c1">// Calls overload D</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Currently, <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> is a bit restricted in terms of its usage:</p>
+<ul class="simple">
+<li>Only one use of <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> is allowed per parameter.</li>
+<li>It is an error to take the address of a function with <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> on
+any of its parameters. If you wish to do this, you can create an overload
+without <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> on any parameters.</li>
+<li>It is an error to apply the <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> attribute to parameters that
+are not pointers. Additionally, any parameter that <tt class="docutils literal"><span class="pre">pass_object_size</span></tt> is
+applied to must be marked <tt class="docutils literal"><span class="pre">const</span></tt> at its function’s definition.</li>
+</ul>
+</div>
+<div class="section" id="require-constant-initialization-clang-require-constant-initialization">
+<h3><a class="toc-backref" href="#id59">require_constant_initialization (clang::require_constant_initialization)</a><a class="headerlink" href="#require-constant-initialization-clang-require-constant-initialization" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies that the variable to which it is attached is intended
+to have a <a class="reference external" href="http://en.cppreference.com/w/cpp/language/constant_initialization">constant initializer</a>
+according to the rules of [basic.start.static]. The variable is required to
+have static or thread storage duration. If the initialization of the variable
+is not a constant initializer an error will be produced. This attribute may
+only be used in C++.</p>
+<p>Note that in C++03 strict constant expression checking is not done. Instead
+the attribute reports if Clang can emit the variable as a constant, even if it’s
+not technically a ‘constant initializer’. This behavior is non-portable.</p>
+<p>Static storage duration variables with constant initializers avoid hard-to-find
+bugs caused by the indeterminate order of dynamic initialization. They can also
+be safely used during dynamic initialization across translation units.</p>
+<p>This attribute acts as a compile time assertion that the requirements
+for constant initialization have been met. Since these requirements change
+between dialects and have subtle pitfalls it’s important to fail fast instead
+of silently falling back on dynamic initialization.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// -std=c++14</span>
+<span class="cp">#define SAFE_STATIC [[clang::require_constant_initialization]]</span>
+<span class="k">struct</span> <span class="n">T</span> <span class="p">{</span>
+  <span class="n">constexpr</span> <span class="n">T</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{}</span>
+  <span class="o">~</span><span class="n">T</span><span class="p">();</span> <span class="c1">// non-trivial</span>
+<span class="p">};</span>
+<span class="n">SAFE_STATIC</span> <span class="n">T</span> <span class="n">x</span> <span class="o">=</span> <span class="p">{</span><span class="mi">42</span><span class="p">};</span> <span class="c1">// Initialization OK. Doesn't check destructor.</span>
+<span class="n">SAFE_STATIC</span> <span class="n">T</span> <span class="n">y</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span> <span class="c1">// error: variable does not have a constant initializer</span>
+<span class="c1">// copy initialization is not a constant expression on a non-literal type.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="section-gnu-section-declspec-allocate">
+<h3><a class="toc-backref" href="#id60">section (gnu::section, __declspec(allocate))</a><a class="headerlink" href="#section-gnu-section-declspec-allocate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">section</span></tt> attribute allows you to specify a specific section a
+global variable or function should be in after translation.</p>
+</div>
+<div class="section" id="swiftcall-gnu-swiftcall">
+<h3><a class="toc-backref" href="#id61">swiftcall (gnu::swiftcall)</a><a class="headerlink" href="#swiftcall-gnu-swiftcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">swiftcall</span></tt> attribute indicates that a function should be called
+using the Swift calling convention for a function or function pointer.</p>
+<p>The lowering for the Swift calling convention, as described by the Swift
+ABI documentation, occurs in multiple phases.  The first, “high-level”
+phase breaks down the formal parameters and results into innately direct
+and indirect components, adds implicit paraameters for the generic
+signature, and assigns the context and error ABI treatments to parameters
+where applicable.  The second phase breaks down the direct parameters
+and results from the first phase and assigns them to registers or the
+stack.  The <tt class="docutils literal"><span class="pre">swiftcall</span></tt> convention only handles this second phase of
+lowering; the C function type must accurately reflect the results
+of the first phase, as follows:</p>
+<ul class="simple">
+<li>Results classified as indirect by high-level lowering should be
+represented as parameters with the <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> attribute.</li>
+<li>Results classified as direct by high-level lowering should be represented
+as follows:<ul>
+<li>First, remove any empty direct results.</li>
+<li>If there are no direct results, the C result type should be <tt class="docutils literal"><span class="pre">void</span></tt>.</li>
+<li>If there is one direct result, the C result type should be a type with
+the exact layout of that result type.</li>
+<li>If there are a multiple direct results, the C result type should be
+a struct type with the exact layout of a tuple of those results.</li>
+</ul>
+</li>
+<li>Parameters classified as indirect by high-level lowering should be
+represented as parameters of pointer type.</li>
+<li>Parameters classified as direct by high-level lowering should be
+omitted if they are empty types; otherwise, they should be represented
+as a parameter type with a layout exactly matching the layout of the
+Swift parameter type.</li>
+<li>The context parameter, if present, should be represented as a trailing
+parameter with the <tt class="docutils literal"><span class="pre">swift_context</span></tt> attribute.</li>
+<li>The error result parameter, if present, should be represented as a
+trailing parameter (always following a context parameter) with the
+<tt class="docutils literal"><span class="pre">swift_error_result</span></tt> attribute.</li>
+</ul>
+<p><tt class="docutils literal"><span class="pre">swiftcall</span></tt> does not support variadic arguments or unprototyped functions.</p>
+<p>The parameter ABI treatment attributes are aspects of the function type.
+A function type which which applies an ABI treatment attribute to a
+parameter is a different type from an otherwise-identical function type
+that does not.  A single parameter may not have multiple ABI treatment
+attributes.</p>
+<p>Support for this feature is target-dependent, although it should be
+supported on every target that Swift supports.  Query for this support
+with <tt class="docutils literal"><span class="pre">__has_attribute(swiftcall)</span></tt>.  This implies support for the
+<tt class="docutils literal"><span class="pre">swift_context</span></tt>, <tt class="docutils literal"><span class="pre">swift_error_result</span></tt>, and <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt>
+attributes.</p>
+</div>
+<div class="section" id="swift-context-gnu-swift-context">
+<h3><a class="toc-backref" href="#id62">swift_context (gnu::swift_context)</a><a class="headerlink" href="#swift-context-gnu-swift-context" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">swift_context</span></tt> attribute marks a parameter of a <tt class="docutils literal"><span class="pre">swiftcall</span></tt>
+function as having the special context-parameter ABI treatment.</p>
+<p>This treatment generally passes the context value in a special register
+which is normally callee-preserved.</p>
+<p>A <tt class="docutils literal"><span class="pre">swift_context</span></tt> parameter must either be the last parameter or must be
+followed by a <tt class="docutils literal"><span class="pre">swift_error_result</span></tt> parameter (which itself must always be
+the last parameter).</p>
+<p>A context parameter must have pointer or reference type.</p>
+</div>
+<div class="section" id="swift-error-result-gnu-swift-error-result">
+<h3><a class="toc-backref" href="#id63">swift_error_result (gnu::swift_error_result)</a><a class="headerlink" href="#swift-error-result-gnu-swift-error-result" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">swift_error_result</span></tt> attribute marks a parameter of a <tt class="docutils literal"><span class="pre">swiftcall</span></tt>
+function as having the special error-result ABI treatment.</p>
+<p>This treatment generally passes the underlying error value in and out of
+the function through a special register which is normally callee-preserved.
+This is modeled in C by pretending that the register is addressable memory:</p>
+<ul class="simple">
+<li>The caller appears to pass the address of a variable of pointer type.
+The current value of this variable is copied into the register before
+the call; if the call returns normally, the value is copied back into the
+variable.</li>
+<li>The callee appears to receive the address of a variable.  This address
+is actually a hidden location in its own stack, initialized with the
+value of the register upon entry.  When the function returns normally,
+the value in that hidden location is written back to the register.</li>
+</ul>
+<p>A <tt class="docutils literal"><span class="pre">swift_error_result</span></tt> parameter must be the last parameter, and it must be
+preceded by a <tt class="docutils literal"><span class="pre">swift_context</span></tt> parameter.</p>
+<p>A <tt class="docutils literal"><span class="pre">swift_error_result</span></tt> parameter must have type <tt class="docutils literal"><span class="pre">T**</span></tt> or <tt class="docutils literal"><span class="pre">T*&</span></tt> for some
+type T.  Note that no qualifiers are permitted on the intermediate level.</p>
+<p>It is undefined behavior if the caller does not pass a pointer or
+reference to a valid object.</p>
+<p>The standard convention is that the error value itself (that is, the
+value stored in the apparent argument) will be null upon function entry,
+but this is not enforced by the ABI.</p>
+</div>
+<div class="section" id="swift-indirect-result-gnu-swift-indirect-result">
+<h3><a class="toc-backref" href="#id64">swift_indirect_result (gnu::swift_indirect_result)</a><a class="headerlink" href="#swift-indirect-result-gnu-swift-indirect-result" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> attribute marks a parameter of a <tt class="docutils literal"><span class="pre">swiftcall</span></tt>
+function as having the special indirect-result ABI treatment.</p>
+<p>This treatment gives the parameter the target’s normal indirect-result
+ABI treatment, which may involve passing it differently from an ordinary
+parameter.  However, only the first indirect result will receive this
+treatment.  Furthermore, low-level lowering may decide that a direct result
+must be returned indirectly; if so, this will take priority over the
+<tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> parameters.</p>
+<p>A <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> parameter must either be the first parameter or
+follow another <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> parameter.</p>
+<p>A <tt class="docutils literal"><span class="pre">swift_indirect_result</span></tt> parameter must have type <tt class="docutils literal"><span class="pre">T*</span></tt> or <tt class="docutils literal"><span class="pre">T&</span></tt> for
+some object type <tt class="docutils literal"><span class="pre">T</span></tt>.  If <tt class="docutils literal"><span class="pre">T</span></tt> is a complete type at the point of
+definition of a function, it is undefined behavior if the argument
+value does not point to storage of adequate size and alignment for a
+value of type <tt class="docutils literal"><span class="pre">T</span></tt>.</p>
+<p>Making indirect results explicit in the signature allows C functions to
+directly construct objects into them without relying on language
+optimizations like C++’s named return value optimization (NRVO).</p>
+</div>
+<div class="section" id="tls-model-gnu-tls-model">
+<h3><a class="toc-backref" href="#id65">tls_model (gnu::tls_model)</a><a class="headerlink" href="#tls-model-gnu-tls-model" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">tls_model</span></tt> attribute allows you to specify which thread-local storage
+model to use. It accepts the following strings:</p>
+<ul class="simple">
+<li>global-dynamic</li>
+<li>local-dynamic</li>
+<li>initial-exec</li>
+<li>local-exec</li>
+</ul>
+<p>TLS models are mutually exclusive.</p>
+</div>
+<div class="section" id="thread">
+<h3><a class="toc-backref" href="#id66">thread</a><a class="headerlink" href="#thread" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">__declspec(thread)</span></tt> attribute declares a variable with thread local
+storage.  It is available under the <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt> flag for MSVC
+compatibility.  See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx">__declspec(thread)</a> on MSDN.</p>
+<p>In Clang, <tt class="docutils literal"><span class="pre">__declspec(thread)</span></tt> is generally equivalent in functionality to the
+GNU <tt class="docutils literal"><span class="pre">__thread</span></tt> keyword.  The variable must not have a destructor and must have
+a constant initializer, if any.  The attribute only applies to variables
+declared with static storage duration, such as globals, class static data
+members, and static locals.</p>
+</div>
+<div class="section" id="maybe-unused-unused-gnu-unused">
+<h3><a class="toc-backref" href="#id67">maybe_unused, unused, gnu::unused</a><a class="headerlink" href="#maybe-unused-unused-gnu-unused" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>When passing the <tt class="docutils literal"><span class="pre">-Wunused</span></tt> flag to Clang, entities that are unused by the
+program may be diagnosed. The <tt class="docutils literal"><span class="pre">[[maybe_unused]]</span></tt> (or
+<tt class="docutils literal"><span class="pre">__attribute__((unused))</span></tt>) attribute can be used to silence such diagnostics
+when the entity cannot be removed. For instance, a local variable may exist
+solely for use in an <tt class="docutils literal"><span class="pre">assert()</span></tt> statement, which makes the local variable
+unused when <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> is defined.</p>
+<p>The attribute may be applied to the declaration of a class, a typedef, a
+variable, a function or method, a function parameter, an enumeration, an
+enumerator, a non-static data member, or a label.</p>
+</div>
+</div>
+<div class="section" id="type-attributes">
+<h2><a class="toc-backref" href="#id68">Type Attributes</a><a class="headerlink" href="#type-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="align-value">
+<h3><a class="toc-backref" href="#id69">align_value</a><a class="headerlink" href="#align-value" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The align_value attribute can be added to the typedef of a pointer type or the
+declaration of a variable of pointer or reference type. It specifies that the
+pointer will point to, or the reference will bind to, only objects with at
+least the provided alignment. This alignment value must be some positive power
+of 2.</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">double</span> <span class="o">*</span> <span class="n">aligned_double_ptr</span> <span class="nf">__attribute__</span><span class="p">((</span><span class="n">align_value</span><span class="p">(</span><span class="mi">64</span><span class="p">)));</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">double</span> <span class="o">&</span> <span class="n">x</span>  <span class="n">__attribute__</span><span class="p">((</span><span class="n">align_value</span><span class="p">(</span><span class="mi">128</span><span class="p">)),</span>
+         <span class="n">aligned_double_ptr</span> <span class="n">y</span><span class="p">)</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>If the pointer value does not have the specified alignment at runtime, the
+behavior of the program is undefined.</p>
+</div>
+<div class="section" id="empty-bases">
+<h3><a class="toc-backref" href="#id70">empty_bases</a><a class="headerlink" href="#empty-bases" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The empty_bases attribute permits the compiler to utilize the
+empty-base-optimization more frequently.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.</p>
+</div>
+<div class="section" id="flag-enum">
+<h3><a class="toc-backref" href="#id71">flag_enum</a><a class="headerlink" href="#flag-enum" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be added to an enumerator to signal to the compiler that it
+is intended to be used as a flag type. This will cause the compiler to assume
+that the range of the type includes all of the values that you can get by
+manipulating bits of the enumerator when issuing warnings.</p>
+</div>
+<div class="section" id="lto-visibility-public-clang-lto-visibility-public">
+<h3><a class="toc-backref" href="#id72">lto_visibility_public (clang::lto_visibility_public)</a><a class="headerlink" href="#lto-visibility-public-clang-lto-visibility-public" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>See <a class="reference internal" href="LTOVisibility.html"><em>LTO Visibility</em></a>.</p>
+</div>
+<div class="section" id="layout-version">
+<h3><a class="toc-backref" href="#id73">layout_version</a><a class="headerlink" href="#layout-version" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The layout_version attribute requests that the compiler utilize the class
+layout rules of a particular compiler version.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.</p>
+</div>
+<div class="section" id="single-inhertiance-multiple-inheritance-virtual-inheritance">
+<h3><a class="toc-backref" href="#id74">__single_inhertiance, __multiple_inheritance, __virtual_inheritance</a><a class="headerlink" href="#single-inhertiance-multiple-inheritance-virtual-inheritance" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This collection of keywords is enabled under <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt> and controls
+the pointer-to-member representation used on <tt class="docutils literal"><span class="pre">*-*-win32</span></tt> targets.</p>
+<p>The <tt class="docutils literal"><span class="pre">*-*-win32</span></tt> targets utilize a pointer-to-member representation which
+varies in size and alignment depending on the definition of the underlying
+class.</p>
+<p>However, this is problematic when a forward declaration is only available and
+no definition has been made yet.  In such cases, Clang is forced to utilize the
+most general representation that is available to it.</p>
+<p>These keywords make it possible to use a pointer-to-member representation other
+than the most general one regardless of whether or not the definition will ever
+be present in the current translation unit.</p>
+<p>This family of keywords belong between the <tt class="docutils literal"><span class="pre">class-key</span></tt> and <tt class="docutils literal"><span class="pre">class-name</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__single_inheritance</span> <span class="n">S</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">S</span><span class="o">::*</span><span class="n">i</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{};</span>
+</pre></div>
+</div>
+<p>This keyword can be applied to class templates but only has an effect when used
+on full specializations:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="p">,</span> <span class="k">typename</span> <span class="n">U</span><span class="o">></span> <span class="k">struct</span> <span class="n">__single_inheritance</span> <span class="n">A</span><span class="p">;</span> <span class="c1">// warning: inheritance model ignored on primary template</span>
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="k">struct</span> <span class="n">__multiple_inheritance</span> <span class="n">A</span><span class="o"><</span><span class="n">T</span><span class="p">,</span> <span class="n">T</span><span class="o">></span><span class="p">;</span> <span class="c1">// warning: inheritance model ignored on partial specialization</span>
+<span class="k">template</span> <span class="o"><></span> <span class="k">struct</span> <span class="n">__single_inheritance</span> <span class="n">A</span><span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="kt">float</span><span class="o">></span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Note that choosing an inheritance model less general than strictly necessary is
+an error:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__multiple_inheritance</span> <span class="n">S</span><span class="p">;</span> <span class="c1">// error: inheritance model does not match definition</span>
+<span class="kt">int</span> <span class="n">S</span><span class="o">::*</span><span class="n">i</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="novtable">
+<h3><a class="toc-backref" href="#id75">novtable</a><a class="headerlink" href="#novtable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be added to a class declaration or definition to signal to
+the compiler that constructors and destructors will not reference the virtual
+function table. It is only supported when using the Microsoft C++ ABI.</p>
+</div>
+<div class="section" id="objc-subclassing-restricted">
+<h3><a class="toc-backref" href="#id76">objc_subclassing_restricted</a><a class="headerlink" href="#objc-subclassing-restricted" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be added to an Objective-C <tt class="docutils literal"><span class="pre">@interface</span></tt> declaration to
+ensure that this class cannot be subclassed.</p>
+</div>
+<div class="section" id="transparent-union-gnu-transparent-union">
+<h3><a class="toc-backref" href="#id77">transparent_union (gnu::transparent_union)</a><a class="headerlink" href="#transparent-union-gnu-transparent-union" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute can be applied to a union to change the behaviour of calls to
+functions that have an argument with a transparent union type. The compiler
+behaviour is changed in the following manner:</p>
+<ul class="simple">
+<li>A value whose type is any member of the transparent union can be passed as an
+argument without the need to cast that value.</li>
+<li>The argument is passed to the function using the calling convention of the
+first member of the transparent union. Consequently, all the members of the
+transparent union should have the same calling convention as its first member.</li>
+</ul>
+<p>Transparent unions are not supported in C++.</p>
+</div>
+</div>
+<div class="section" id="statement-attributes">
+<h2><a class="toc-backref" href="#id78">Statement Attributes</a><a class="headerlink" href="#statement-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="fallthrough-clang-fallthrough">
+<h3><a class="toc-backref" href="#id79">fallthrough, clang::fallthrough</a><a class="headerlink" href="#fallthrough-clang-fallthrough" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">fallthrough</span></tt> (or <tt class="docutils literal"><span class="pre">clang::fallthrough</span></tt>) attribute is used
+to annotate intentional fall-through
+between switch labels.  It can only be applied to a null statement placed at a
+point of execution between any statement and the next switch label.  It is
+common to mark these places with a specific comment, but this attribute is
+meant to replace comments with a more strict annotation, which can be checked
+by the compiler.  This attribute doesn’t change semantics of the code and can
+be used wherever an intended fall-through occurs.  It is designed to mimic
+control-flow statements like <tt class="docutils literal"><span class="pre">break;</span></tt>, so it can be placed in most places
+where <tt class="docutils literal"><span class="pre">break;</span></tt> can, but only if there are no statements on the execution path
+between it and the next switch label.</p>
+<p>By default, Clang does not warn on unannotated fallthrough from one <tt class="docutils literal"><span class="pre">switch</span></tt>
+case to another. Diagnostics on fallthrough without a corresponding annotation
+can be enabled with the <tt class="docutils literal"><span class="pre">-Wimplicit-fallthrough</span></tt> argument.</p>
+<p>Here is an example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// compile with -Wimplicit-fallthrough</span>
+<span class="k">switch</span> <span class="p">(</span><span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+<span class="k">case</span> <span class="mi">22</span>:
+<span class="k">case</span> <span class="mi">33</span>:  <span class="c1">// no warning: no statements between case labels</span>
+  <span class="n">f</span><span class="p">();</span>
+<span class="k">case</span> <span class="mi">44</span>:  <span class="c1">// warning: unannotated fall-through</span>
+  <span class="n">g</span><span class="p">();</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span>
+<span class="k">case</span> <span class="mi">55</span>:  <span class="c1">// no warning</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">h</span><span class="p">();</span>
+    <span class="k">break</span><span class="p">;</span>
+  <span class="p">}</span>
+  <span class="k">else</span> <span class="p">{</span>
+    <span class="n">i</span><span class="p">();</span>
+    <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span>
+  <span class="p">}</span>
+<span class="k">case</span> <span class="mi">66</span>:  <span class="c1">// no warning</span>
+  <span class="n">p</span><span class="p">();</span>
+  <span class="p">[[</span><span class="n">clang</span><span class="o">::</span><span class="n">fallthrough</span><span class="p">]];</span> <span class="c1">// warning: fallthrough annotation does not</span>
+                          <span class="c1">//          directly precede case label</span>
+  <span class="n">q</span><span class="p">();</span>
+<span class="k">case</span> <span class="mi">77</span>:  <span class="c1">// warning: unannotated fall-through</span>
+  <span class="n">r</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="pragma-clang-loop">
+<h3><a class="toc-backref" href="#id80">#pragma clang loop</a><a class="headerlink" href="#pragma-clang-loop" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span></tt> directive allows loop optimization hints to be
+specified for the subsequent loop. The directive allows vectorization,
+interleaving, and unrolling to be enabled or disabled. Vector width as well
+as interleave and unrolling count can be manually specified. See
+<a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations">language extensions</a>
+for details.</p>
+</div>
+<div class="section" id="pragma-unroll-pragma-nounroll">
+<h3><a class="toc-backref" href="#id81">#pragma unroll, #pragma nounroll</a><a class="headerlink" href="#pragma-unroll-pragma-nounroll" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+</tr>
+</tbody>
+</table>
+<p>Loop unrolling optimization hints can be specified with <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">unroll</span></tt> and
+<tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">nounroll</span></tt>. The pragma is placed immediately before a for, while,
+do-while, or c++11 range-based for loop.</p>
+<p>Specifying <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">unroll</span></tt> without a parameter directs the loop unroller to
+attempt to fully unroll the loop if the trip count is known at compile time and
+attempt to partially unroll the loop if the trip count is not known at compile
+time:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma unroll</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Specifying the optional parameter, <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">unroll</span> <span class="pre">_value_</span></tt>, directs the
+unroller to unroll the loop <tt class="docutils literal"><span class="pre">_value_</span></tt> times.  The parameter may optionally be
+enclosed in parentheses:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma unroll 16</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+
+<span class="cp">#pragma unroll(16)</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Specifying <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">nounroll</span></tt> indicates that the loop should not be unrolled:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#pragma nounroll</span>
+<span class="k">for</span> <span class="p">(...)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">unroll</span></tt> and <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">unroll</span> <span class="pre">_value_</span></tt> have identical semantics to
+<tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span> <span class="pre">unroll(full)</span></tt> and
+<tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span> <span class="pre">unroll_count(_value_)</span></tt> respectively. <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">nounroll</span></tt>
+is equivalent to <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">clang</span> <span class="pre">loop</span> <span class="pre">unroll(disable)</span></tt>.  See
+<a class="reference external" href="http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations">language extensions</a>
+for further details including limitations of the unroll hints.</p>
+</div>
+<div class="section" id="read-only-write-only-read-write-read-only-write-only-read-write">
+<h3><a class="toc-backref" href="#id82">__read_only, __write_only, __read_write (read_only, write_only, read_write)</a><a class="headerlink" href="#read-only-write-only-read-write-read-only-write-only-read-write" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The access qualifiers must be used with image object arguments or pipe arguments
+to declare if they are being read or written by a kernel or function.</p>
+<p>The read_only/__read_only, write_only/__write_only and read_write/__read_write
+names are reserved for use as access qualifiers and shall not be used otherwise.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">kernel</span> <span class="kt">void</span>
+<span class="nf">foo</span> <span class="p">(</span><span class="n">read_only</span> <span class="kt">image2d_t</span> <span class="n">imageA</span><span class="p">,</span>
+     <span class="n">write_only</span> <span class="kt">image2d_t</span> <span class="n">imageB</span><span class="p">)</span> <span class="p">{</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In the above example imageA is a read-only 2D image object, and imageB is a
+write-only 2D image object.</p>
+<p>The read_write (or __read_write) qualifier can not be used with pipe.</p>
+<p>More details can be found in the OpenCL C language Spec v2.0, Section 6.6.</p>
+</div>
+<div class="section" id="attribute-opencl-unroll-hint">
+<h3><a class="toc-backref" href="#id83">__attribute__((opencl_unroll_hint))</a><a class="headerlink" href="#attribute-opencl-unroll-hint" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The opencl_unroll_hint attribute qualifier can be used to specify that a loop
+(for, while and do loops) can be unrolled. This attribute qualifier can be
+used to specify full unrolling or partial unrolling by a specified amount.
+This is a compiler hint and the compiler may ignore this directive. See
+<a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf">OpenCL v2.0</a>
+s6.11.5 for details.</p>
+</div>
+</div>
+<div class="section" id="type-safety-checking">
+<h2><a class="toc-backref" href="#id84">Type Safety Checking</a><a class="headerlink" href="#type-safety-checking" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports additional attributes to enable checking type safety properties
+that can’t be enforced by the C type system. To see warnings produced by these
+checks, ensure that -Wtype-safety is enabled. Use cases include:</p>
+<ul class="simple">
+<li>MPI library implementations, where these attributes enable checking that
+the buffer type matches the passed <tt class="docutils literal"><span class="pre">MPI_Datatype</span></tt>;</li>
+<li>for HDF5 library there is a similar use case to MPI;</li>
+<li>checking types of variadic functions’ arguments for functions like
+<tt class="docutils literal"><span class="pre">fcntl()</span></tt> and <tt class="docutils literal"><span class="pre">ioctl()</span></tt>.</li>
+</ul>
+<p>You can detect support for these attributes with <tt class="docutils literal"><span class="pre">__has_attribute()</span></tt>.  For
+example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#if defined(__has_attribute)</span>
+<span class="cp">#  if __has_attribute(argument_with_type_tag) && \</span>
+<span class="cp">      __has_attribute(pointer_with_type_tag) && \</span>
+<span class="cp">      __has_attribute(type_tag_for_datatype)</span>
+<span class="cp">#    define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))</span>
+<span class="cm">/* ... other macros ...  */</span>
+<span class="cp">#  endif</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if !defined(ATTR_MPI_PWT)</span>
+<span class="cp"># define ATTR_MPI_PWT(buffer_idx, type_idx)</span>
+<span class="cp">#endif</span>
+
+<span class="kt">int</span> <span class="nf">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span> <span class="cm">/*, other args omitted */</span><span class="p">)</span>
+    <span class="n">ATTR_MPI_PWT</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">);</span>
+</pre></div>
+</div>
+<div class="section" id="argument-with-type-tag">
+<h3><a class="toc-backref" href="#id85">argument_with_type_tag</a><a class="headerlink" href="#argument-with-type-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((argument_with_type_tag(arg_kind,</span> <span class="pre">arg_idx,</span>
+<span class="pre">type_tag_idx)))</span></tt> on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.</p>
+<p>This attribute is primarily useful for checking arguments of variadic functions
+(<tt class="docutils literal"><span class="pre">pointer_with_type_tag</span></tt> can be used in most non-variadic cases).</p>
+<dl class="docutils">
+<dt>In the attribute prototype above:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">arg_kind</span></tt> is an identifier that should be used when annotating all
+applicable type tags.</li>
+<li><tt class="docutils literal"><span class="pre">arg_idx</span></tt> provides the position of a function argument. The expected type of
+this function argument will be determined by the function argument specified
+by <tt class="docutils literal"><span class="pre">type_tag_idx</span></tt>. In the code example below, “3” means that the type of the
+function’s third argument will be determined by <tt class="docutils literal"><span class="pre">type_tag_idx</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">type_tag_idx</span></tt> provides the position of a function argument. This function
+argument will be a type tag. The type tag will determine the expected type of
+the argument specified by <tt class="docutils literal"><span class="pre">arg_idx</span></tt>. In the code example below, “2” means
+that the type tag associated with the function’s second argument should agree
+with the type of the argument specified by <tt class="docutils literal"><span class="pre">arg_idx</span></tt>.</li>
+</ul>
+</dd>
+</dl>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">fcntl</span><span class="p">(</span><span class="kt">int</span> <span class="n">fd</span><span class="p">,</span> <span class="kt">int</span> <span class="n">cmd</span><span class="p">,</span> <span class="p">...)</span>
+    <span class="n">__attribute__</span><span class="p">((</span> <span class="n">argument_with_type_tag</span><span class="p">(</span><span class="n">fcntl</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span> <span class="p">));</span>
+<span class="c1">// The function's second argument will be a type tag; this type tag will</span>
+<span class="c1">// determine the expected type of the function's third argument.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="pointer-with-type-tag">
+<h3><a class="toc-backref" href="#id86">pointer_with_type_tag</a><a class="headerlink" href="#pointer-with-type-tag" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((pointer_with_type_tag(ptr_kind,</span> <span class="pre">ptr_idx,</span> <span class="pre">type_tag_idx)))</span></tt>
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.</p>
+<dl class="docutils">
+<dt>In the attribute prototype above:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">ptr_kind</span></tt> is an identifier that should be used when annotating all
+applicable type tags.</li>
+<li><tt class="docutils literal"><span class="pre">ptr_idx</span></tt> provides the position of a function argument; this function
+argument will have a pointer type. The expected pointee type of this pointer
+type will be determined by the function argument specified by
+<tt class="docutils literal"><span class="pre">type_tag_idx</span></tt>. In the code example below, “1” means that the pointee type
+of the function’s first argument will be determined by <tt class="docutils literal"><span class="pre">type_tag_idx</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">type_tag_idx</span></tt> provides the position of a function argument; this function
+argument will be a type tag. The type tag will determine the expected pointee
+type of the pointer argument specified by <tt class="docutils literal"><span class="pre">ptr_idx</span></tt>. In the code example
+below, “3” means that the type tag associated with the function’s third
+argument should agree with the pointee type of the pointer argument specified
+by <tt class="docutils literal"><span class="pre">ptr_idx</span></tt>.</li>
+</ul>
+</dd>
+</dl>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="kt">int</span> <span class="nf">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span> <span class="cm">/*, other args omitted */</span><span class="p">)</span>
+    <span class="n">__attribute__</span><span class="p">((</span> <span class="n">pointer_with_type_tag</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="p">));</span>
+<span class="c1">// The function's 3rd argument will be a type tag; this type tag will</span>
+<span class="c1">// determine the expected pointee type of the function's 1st argument.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="type-tag-for-datatype">
+<h3><a class="toc-backref" href="#id87">type_tag_for_datatype</a><a class="headerlink" href="#type-tag-for-datatype" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>When declaring a variable, use
+<tt class="docutils literal"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></tt> to create a type tag that
+is tied to the <tt class="docutils literal"><span class="pre">type</span></tt> argument given to the attribute.</p>
+<dl class="docutils">
+<dt>In the attribute prototype above:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">kind</span></tt> is an identifier that should be used when annotating all applicable
+type tags.</li>
+<li><tt class="docutils literal"><span class="pre">type</span></tt> indicates the name of the type.</li>
+</ul>
+</dd>
+</dl>
+<p>Clang supports annotating type tags of two forms.</p>
+<blockquote>
+<div><ul>
+<li><p class="first"><strong>Type tag that is a reference to a declared identifier.</strong>
+Use <tt class="docutils literal"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></tt> when declaring that
+identifier:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_int</span>
+    <span class="nf">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="kt">int</span><span class="p">)</span> <span class="p">));</span>
+<span class="cp">#define MPI_INT ((MPI_Datatype) &mpi_datatype_int)</span>
+<span class="c1">// &mpi_datatype_int is a type tag. It is tied to type "int".</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><strong>Type tag that is an integral literal.</strong>
+Declare a <tt class="docutils literal"><span class="pre">static</span> <span class="pre">const</span></tt> variable with an initializer value and attach
+<tt class="docutils literal"><span class="pre">__attribute__((type_tag_for_datatype(kind,</span> <span class="pre">type)))</span></tt> on that declaration:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">static</span> <span class="k">const</span> <span class="n">MPI_Datatype</span> <span class="n">mpi_datatype_int</span>
+    <span class="n">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="kt">int</span><span class="p">)</span> <span class="p">))</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span>
+<span class="cp">#define MPI_INT ((MPI_Datatype) 42)</span>
+<span class="c1">// The number 42 is a type tag. It is tied to type "int".</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div></blockquote>
+<p>The <tt class="docutils literal"><span class="pre">type_tag_for_datatype</span></tt> attribute also accepts an optional third argument
+that determines how the type of the function argument specified by either
+<tt class="docutils literal"><span class="pre">arg_idx</span></tt> or <tt class="docutils literal"><span class="pre">ptr_idx</span></tt> is compared against the type associated with the type
+tag. (Recall that for the <tt class="docutils literal"><span class="pre">argument_with_type_tag</span></tt> attribute, the type of the
+function argument specified by <tt class="docutils literal"><span class="pre">arg_idx</span></tt> is compared against the type
+associated with the type tag. Also recall that for the <tt class="docutils literal"><span class="pre">pointer_with_type_tag</span></tt>
+attribute, the pointee type of the function argument specified by <tt class="docutils literal"><span class="pre">ptr_idx</span></tt> is
+compared against the type associated with the type tag.) There are two supported
+values for this optional third argument:</p>
+<blockquote>
+<div><ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">layout_compatible</span></tt> will cause types to be compared according to
+layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the
+layout-compatibility rules for two standard-layout struct types and for two
+standard-layout union types). This is useful when creating a type tag
+associated with a struct or union type. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cm">/* In mpi.h */</span>
+<span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">struct</span> <span class="n">internal_mpi_double_int</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">d</span><span class="p">;</span> <span class="kt">int</span> <span class="n">i</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_double_int</span>
+    <span class="nf">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span>
+                    <span class="k">struct</span> <span class="n">internal_mpi_double_int</span><span class="p">,</span> <span class="n">layout_compatible</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cp">#define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)</span>
+
+<span class="kt">int</span> <span class="nf">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span><span class="p">,</span> <span class="p">...)</span>
+    <span class="n">__attribute__</span><span class="p">((</span> <span class="n">pointer_with_type_tag</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cm">/* In user code */</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="o">*</span><span class="n">buffer</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DOUBLE_INT</span> <span class="cm">/*, ...  */</span><span class="p">);</span> <span class="c1">// no warning because the</span>
+                                                 <span class="c1">// layout of my_pair is</span>
+                                                 <span class="c1">// compatible with that of</span>
+                                                 <span class="c1">// internal_mpi_double_int</span>
+
+<span class="k">struct</span> <span class="n">my_int_pair</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">}</span>
+<span class="k">struct</span> <span class="n">my_int_pair</span> <span class="o">*</span><span class="n">buffer2</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer2</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DOUBLE_INT</span> <span class="cm">/*, ...  */</span><span class="p">);</span> <span class="c1">// warning because the</span>
+                                                  <span class="c1">// layout of my_int_pair</span>
+                                                  <span class="c1">// does not match that of</span>
+                                                  <span class="c1">// internal_mpi_double_int</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">must_be_null</span></tt> specifies that the function argument specified by either
+<tt class="docutils literal"><span class="pre">arg_idx</span></tt> (for the <tt class="docutils literal"><span class="pre">argument_with_type_tag</span></tt> attribute) or <tt class="docutils literal"><span class="pre">ptr_idx</span></tt> (for
+the <tt class="docutils literal"><span class="pre">pointer_with_type_tag</span></tt> attribute) should be a null pointer constant.
+The second argument to the <tt class="docutils literal"><span class="pre">type_tag_for_datatype</span></tt> attribute is ignored. For
+example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cm">/* In mpi.h */</span>
+<span class="k">typedef</span> <span class="kt">int</span> <span class="n">MPI_Datatype</span><span class="p">;</span>
+<span class="k">extern</span> <span class="k">struct</span> <span class="n">mpi_datatype</span> <span class="n">mpi_datatype_null</span>
+    <span class="nf">__attribute__</span><span class="p">((</span> <span class="n">type_tag_for_datatype</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span> <span class="kt">void</span><span class="p">,</span> <span class="n">must_be_null</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cp">#define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)</span>
+<span class="kt">int</span> <span class="nf">MPI_Send</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="kt">int</span> <span class="n">count</span><span class="p">,</span> <span class="n">MPI_Datatype</span> <span class="n">datatype</span><span class="p">,</span> <span class="p">...)</span>
+    <span class="n">__attribute__</span><span class="p">((</span> <span class="n">pointer_with_type_tag</span><span class="p">(</span><span class="n">mpi</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="p">));</span>
+
+<span class="cm">/* In user code */</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="p">{</span> <span class="kt">double</span> <span class="n">a</span><span class="p">;</span> <span class="kt">int</span> <span class="n">b</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">my_pair</span> <span class="o">*</span><span class="n">buffer</span><span class="p">;</span>
+<span class="n">MPI_Send</span><span class="p">(</span><span class="n">buffer</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">MPI_DATATYPE_NULL</span> <span class="cm">/*, ...  */</span><span class="p">);</span> <span class="c1">// warning: MPI_DATATYPE_NULL</span>
+                                                    <span class="c1">// was specified but buffer</span>
+                                                    <span class="c1">// is not a null pointer</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="amd-gpu-attributes">
+<h2><a class="toc-backref" href="#id88">AMD GPU Attributes</a><a class="headerlink" href="#amd-gpu-attributes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="amdgpu-flat-work-group-size">
+<h3><a class="toc-backref" href="#id89">amdgpu_flat_work_group_size</a><a class="headerlink" href="#amdgpu-flat-work-group-size" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The flat work-group size is the number of work-items in the work-group size
+specified when the kernel is dispatched. It is the product of the sizes of the
+x, y, and z dimension of the work-group.</p>
+<p>Clang supports the
+<tt class="docutils literal"><span class="pre">__attribute__((amdgpu_flat_work_group_size(<min>,</span> <span class="pre"><max>)))</span></tt> attribute for the
+AMDGPU target. This attribute may be attached to a kernel function definition
+and is an optimization hint.</p>
+<p><tt class="docutils literal"><span class="pre"><min></span></tt> parameter specifies the minimum flat work-group size, and <tt class="docutils literal"><span class="pre"><max></span></tt>
+parameter specifies the maximum flat work-group size (must be greater than
+<tt class="docutils literal"><span class="pre"><min></span></tt>) to which all dispatches of the kernel will conform. Passing <tt class="docutils literal"><span class="pre">0,</span> <span class="pre">0</span></tt>
+as <tt class="docutils literal"><span class="pre"><min>,</span> <span class="pre"><max></span></tt> implies the default behavior (<tt class="docutils literal"><span class="pre">128,</span> <span class="pre">256</span></tt>).</p>
+<p>If specified, the AMDGPU target backend might be able to produce better machine
+code for barriers and perform scratch promotion by estimating available group
+segment size.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="amdgpu-num-sgpr">
+<h3><a class="toc-backref" href="#id90">amdgpu_num_sgpr</a><a class="headerlink" href="#amdgpu-num-sgpr" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">__attribute__((amdgpu_num_sgpr(<num_sgpr>)))</span></tt> and
+<tt class="docutils literal"><span class="pre">__attribute__((amdgpu_num_vgpr(<num_vgpr>)))</span></tt> attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.</p>
+<p>If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing <tt class="docutils literal"><span class="pre">0</span></tt> as
+<tt class="docutils literal"><span class="pre">num_sgpr</span></tt> and/or <tt class="docutils literal"><span class="pre">num_vgpr</span></tt> implies the default behavior (no limits).</p>
+<p>These attributes can be used to test the AMDGPU target backend. It is
+recommended that the <tt class="docutils literal"><span class="pre">amdgpu_waves_per_eu</span></tt> attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes;</li>
+<li>The AMDGPU target backend is unable to create machine code that can meet the
+request.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="amdgpu-num-vgpr">
+<h3><a class="toc-backref" href="#id91">amdgpu_num_vgpr</a><a class="headerlink" href="#amdgpu-num-vgpr" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">__attribute__((amdgpu_num_sgpr(<num_sgpr>)))</span></tt> and
+<tt class="docutils literal"><span class="pre">__attribute__((amdgpu_num_vgpr(<num_vgpr>)))</span></tt> attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.</p>
+<p>If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing <tt class="docutils literal"><span class="pre">0</span></tt> as
+<tt class="docutils literal"><span class="pre">num_sgpr</span></tt> and/or <tt class="docutils literal"><span class="pre">num_vgpr</span></tt> implies the default behavior (no limits).</p>
+<p>These attributes can be used to test the AMDGPU target backend. It is
+recommended that the <tt class="docutils literal"><span class="pre">amdgpu_waves_per_eu</span></tt> attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes;</li>
+<li>The AMDGPU target backend is unable to create machine code that can meet the
+request.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="amdgpu-waves-per-eu">
+<h3><a class="toc-backref" href="#id92">amdgpu_waves_per_eu</a><a class="headerlink" href="#amdgpu-waves-per-eu" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>A compute unit (CU) is responsible for executing the wavefronts of a work-group.
+It is composed of one or more execution units (EU), which are responsible for
+executing the wavefronts. An EU can have enough resources to maintain the state
+of more than one executing wavefront. This allows an EU to hide latency by
+switching between wavefronts in a similar way to symmetric multithreading on a
+CPU. In order to allow the state for multiple wavefronts to fit on an EU, the
+resources used by a single wavefront have to be limited. For example, the number
+of SGPRs and VGPRs. Limiting such resources can allow greater latency hiding,
+but can result in having to spill some register state to memory.</p>
+<p>Clang supports the <tt class="docutils literal"><span class="pre">__attribute__((amdgpu_waves_per_eu(<min>[,</span> <span class="pre"><max>])))</span></tt>
+attribute for the AMDGPU target. This attribute may be attached to a kernel
+function definition and is an optimization hint.</p>
+<p><tt class="docutils literal"><span class="pre"><min></span></tt> parameter specifies the requested minimum number of waves per EU, and
+<em>optional</em> <tt class="docutils literal"><span class="pre"><max></span></tt> parameter specifies the requested maximum number of waves
+per EU (must be greater than <tt class="docutils literal"><span class="pre"><min></span></tt> if specified). If <tt class="docutils literal"><span class="pre"><max></span></tt> is omitted,
+then there is no restriction on the maximum number of waves per EU other than
+the one dictated by the hardware for which the kernel is compiled. Passing
+<tt class="docutils literal"><span class="pre">0,</span> <span class="pre">0</span></tt> as <tt class="docutils literal"><span class="pre"><min>,</span> <span class="pre"><max></span></tt> implies the default behavior (no limits).</p>
+<p>If specified, this attribute allows an advanced developer to tune the number of
+wavefronts that are capable of fitting within the resources of an EU. The AMDGPU
+target backend can use this information to limit resources, such as number of
+SGPRs, number of VGPRs, size of available group and private memory segments, in
+such a way that guarantees that at least <tt class="docutils literal"><span class="pre"><min></span></tt> wavefronts and at most
+<tt class="docutils literal"><span class="pre"><max></span></tt> wavefronts are able to fit within the resources of an EU. Requesting
+more wavefronts can hide memory latency but limits available registers which
+can result in spilling. Requesting fewer wavefronts can help reduce cache
+thrashing, but can reduce memory latency hiding.</p>
+<p>This attribute controls the machine code generated by the AMDGPU target backend
+to ensure it is capable of meeting the requested values. However, when the
+kernel is executed, there may be other reasons that prevent meeting the request,
+for example, there may be wavefronts from other kernels executing on the EU.</p>
+<dl class="docutils">
+<dt>An error will be given if:</dt>
+<dd><ul class="first last simple">
+<li>Specified values violate subtarget specifications;</li>
+<li>Specified values are not compatible with values provided through other
+attributes;</li>
+<li>The AMDGPU target backend is unable to create machine code that can meet the
+request.</li>
+</ul>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section" id="calling-conventions">
+<h2><a class="toc-backref" href="#id93">Calling Conventions</a><a class="headerlink" href="#calling-conventions" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports several different calling conventions, depending on the target
+platform and architecture. The calling convention used for a function determines
+how parameters are passed, how results are returned to the caller, and other
+low-level details of calling a function.</p>
+<div class="section" id="fastcall-gnu-fastcall-fastcall-fastcall">
+<h3><a class="toc-backref" href="#id94">fastcall (gnu::fastcall, __fastcall, _fastcall)</a><a class="headerlink" href="#fastcall-gnu-fastcall-fastcall-fastcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX and EDX as register parameters and clear parameters off of
+the stack on return. This convention does not support variadic calls or
+unprototyped functions in C, and has no effect on x86_64 targets. This calling
+convention is supported primarily for compatibility with existing code. Users
+seeking register parameters should use the <tt class="docutils literal"><span class="pre">regparm</span></tt> attribute, which does
+not require callee-cleanup.  See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/6xa169sk.aspx">__fastcall</a> on MSDN.</p>
+</div>
+<div class="section" id="ms-abi-gnu-ms-abi">
+<h3><a class="toc-backref" href="#id95">ms_abi (gnu::ms_abi)</a><a class="headerlink" href="#ms-abi-gnu-ms-abi" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On non-Windows x86_64 targets, this attribute changes the calling convention of
+a function to match the default convention used on Windows x86_64. This
+attribute has no effect on Windows targets or non-x86_64 targets.</p>
+</div>
+<div class="section" id="pcs-gnu-pcs">
+<h3><a class="toc-backref" href="#id96">pcs (gnu::pcs)</a><a class="headerlink" href="#pcs-gnu-pcs" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On ARM targets, this attribute can be used to select calling conventions
+similar to <tt class="docutils literal"><span class="pre">stdcall</span></tt> on x86. Valid parameter values are “aapcs” and
+“aapcs-vfp”.</p>
+</div>
+<div class="section" id="preserve-all">
+<h3><a class="toc-backref" href="#id97">preserve_all</a><a class="headerlink" href="#preserve-all" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The <tt class="docutils literal"><span class="pre">preserve_all</span></tt> calling convention attempts to make the code
+in the caller even less intrusive than the <tt class="docutils literal"><span class="pre">preserve_most</span></tt> calling convention.
+This calling convention also behaves identical to the <tt class="docutils literal"><span class="pre">C</span></tt> calling convention
+on how arguments and return values are passed, but it uses a different set of
+caller/callee-saved registers. This removes the burden of saving and
+recovering a large register set before and after the call in the caller. If
+the arguments are passed in callee-saved registers, then they will be
+preserved by the callee across the call. This doesn’t apply for values
+returned in callee-saved registers.</p>
+<ul class="simple">
+<li>On X86-64 the callee preserves all general purpose registers, except for
+R11. R11 can be used as a scratch register. Furthermore it also preserves
+all floating-point registers (XMMs/YMMs).</li>
+</ul>
+<p>The idea behind this convention is to support calls to runtime functions
+that don’t need to call out to any other functions.</p>
+<p>This calling convention, like the <tt class="docutils literal"><span class="pre">preserve_most</span></tt> calling convention, will be
+used by a future version of the Objective-C runtime and should be considered
+experimental at this time.</p>
+</div>
+<div class="section" id="preserve-most">
+<h3><a class="toc-backref" href="#id98">preserve_most</a><a class="headerlink" href="#preserve-most" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The <tt class="docutils literal"><span class="pre">preserve_most</span></tt> calling convention attempts to make the code
+in the caller as unintrusive as possible. This convention behaves identically
+to the <tt class="docutils literal"><span class="pre">C</span></tt> calling convention on how arguments and return values are passed,
+but it uses a different set of caller/callee-saved registers. This alleviates
+the burden of saving and recovering a large register set before and after the
+call in the caller. If the arguments are passed in callee-saved registers,
+then they will be preserved by the callee across the call. This doesn’t
+apply for values returned in callee-saved registers.</p>
+<ul class="simple">
+<li>On X86-64 the callee preserves all general purpose registers, except for
+R11. R11 can be used as a scratch register. Floating-point registers
+(XMMs/YMMs) are not preserved and need to be saved by the caller.</li>
+</ul>
+<p>The idea behind this convention is to support calls to runtime functions
+that have a hot path and a cold path. The hot path is usually a small piece
+of code that doesn’t use many registers. The cold path might need to call out to
+another function and therefore only needs to preserve the caller-saved
+registers, which haven’t already been saved by the caller. The
+<cite>preserve_most</cite> calling convention is very similar to the <tt class="docutils literal"><span class="pre">cold</span></tt> calling
+convention in terms of caller/callee-saved registers, but they are used for
+different types of function calls. <tt class="docutils literal"><span class="pre">coldcc</span></tt> is for function calls that are
+rarely executed, whereas <cite>preserve_most</cite> function calls are intended to be
+on the hot path and definitely executed a lot. Furthermore <tt class="docutils literal"><span class="pre">preserve_most</span></tt>
+doesn’t prevent the inliner from inlining the function call.</p>
+<p>This calling convention will be used by a future version of the Objective-C
+runtime and should therefore still be considered experimental at this time.
+Although this convention was created to optimize certain runtime calls to
+the Objective-C runtime, it is not limited to this runtime and might be used
+by other runtimes in the future too. The current implementation only
+supports X86-64 and AArch64, but the intention is to support more architectures
+in the future.</p>
+</div>
+<div class="section" id="regcall-gnu-regcall-regcall">
+<h3><a class="toc-backref" href="#id99">regcall (gnu::regcall, __regcall)</a><a class="headerlink" href="#regcall-gnu-regcall-regcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On x86 targets, this attribute changes the calling convention to
+<a class="reference external" href="https://software.intel.com/en-us/node/693069">__regcall</a> convention. This convention aims to pass as many arguments
+as possible in registers. It also tries to utilize registers for the
+return value whenever it is possible.</p>
+</div>
+<div class="section" id="regparm-gnu-regparm">
+<h3><a class="toc-backref" href="#id100">regparm (gnu::regparm)</a><a class="headerlink" href="#regparm-gnu-regparm" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, the regparm attribute causes the compiler to pass
+the first three integer parameters in EAX, EDX, and ECX instead of on the
+stack. This attribute has no effect on variadic functions, and all parameters
+are passed via the stack as normal.</p>
+</div>
+<div class="section" id="stdcall-gnu-stdcall-stdcall-stdcall">
+<h3><a class="toc-backref" href="#id101">stdcall (gnu::stdcall, __stdcall, _stdcall)</a><a class="headerlink" href="#stdcall-gnu-stdcall-stdcall-stdcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, this attribute changes the calling convention of a
+function to clear parameters off of the stack on return. This convention does
+not support variadic calls or unprototyped functions in C, and has no effect on
+x86_64 targets. This calling convention is used widely by the Windows API and
+COM applications.  See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx">__stdcall</a> on MSDN.</p>
+</div>
+<div class="section" id="thiscall-gnu-thiscall-thiscall-thiscall">
+<h3><a class="toc-backref" href="#id102">thiscall (gnu::thiscall, __thiscall, _thiscall)</a><a class="headerlink" href="#thiscall-gnu-thiscall-thiscall-thiscall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX for the first parameter (typically the implicit <tt class="docutils literal"><span class="pre">this</span></tt>
+parameter of C++ methods) and clear parameters off of the stack on return. This
+convention does not support variadic calls or unprototyped functions in C, and
+has no effect on x86_64 targets. See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx">__thiscall</a> on
+MSDN.</p>
+</div>
+<div class="section" id="vectorcall-vectorcall-vectorcall">
+<h3><a class="toc-backref" href="#id103">vectorcall (__vectorcall, _vectorcall)</a><a class="headerlink" href="#vectorcall-vectorcall-vectorcall" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>On 32-bit x86 <em>and</em> x86_64 targets, this attribute changes the calling
+convention of a function to pass vector parameters in SSE registers.</p>
+<p>On 32-bit x86 targets, this calling convention is similar to <tt class="docutils literal"><span class="pre">__fastcall</span></tt>.
+The first two integer parameters are passed in ECX and EDX. Subsequent integer
+parameters are passed in memory, and callee clears the stack.  On x86_64
+targets, the callee does <em>not</em> clear the stack, and integer parameters are
+passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling
+convention.</p>
+<p>On both 32-bit x86 and x86_64 targets, vector and floating point arguments are
+passed in XMM0-XMM5. Homogeneous vector aggregates of up to four elements are
+passed in sequential SSE registers if enough are available. If AVX is enabled,
+256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that
+cannot be passed in registers for any reason is passed by reference, which
+allows the caller to align the parameter memory.</p>
+<p>See the documentation for <a class="reference external" href="http://msdn.microsoft.com/en-us/library/dn375768.aspx">__vectorcall</a> on MSDN for more details.</p>
+</div>
+</div>
+<div class="section" id="consumed-annotation-checking">
+<h2><a class="toc-backref" href="#id104">Consumed Annotation Checking</a><a class="headerlink" href="#consumed-annotation-checking" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although <strong>the implementation
+for these annotations is currently in development and are subject to change.</strong></p>
+<div class="section" id="callable-when">
+<h3><a class="toc-backref" href="#id105">callable_when</a><a class="headerlink" href="#callable-when" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((callable_when(...)))</span></tt> to indicate what states a method
+may be called in.  Valid states are unconsumed, consumed, or unknown.  Each
+argument to this attribute must be a quoted string.  E.g.:</p>
+<p><tt class="docutils literal"><span class="pre">__attribute__((callable_when("unconsumed",</span> <span class="pre">"unknown")))</span></tt></p>
+</div>
+<div class="section" id="consumable">
+<h3><a class="toc-backref" href="#id106">consumable</a><a class="headerlink" href="#consumable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Each <tt class="docutils literal"><span class="pre">class</span></tt> that uses any of the typestate annotations must first be marked
+using the <tt class="docutils literal"><span class="pre">consumable</span></tt> attribute.  Failure to do so will result in a warning.</p>
+<p>This attribute accepts a single parameter that must be one of the following:
+<tt class="docutils literal"><span class="pre">unknown</span></tt>, <tt class="docutils literal"><span class="pre">consumed</span></tt>, or <tt class="docutils literal"><span class="pre">unconsumed</span></tt>.</p>
+</div>
+<div class="section" id="param-typestate">
+<h3><a class="toc-backref" href="#id107">param_typestate</a><a class="headerlink" href="#param-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>This attribute specifies expectations about function parameters.  Calls to an
+function with annotated parameters will issue a warning if the corresponding
+argument isn’t in the expected state.  The attribute is also used to set the
+initial state of the parameter when analyzing the function’s body.</p>
+</div>
+<div class="section" id="return-typestate">
+<h3><a class="toc-backref" href="#id108">return_typestate</a><a class="headerlink" href="#return-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">return_typestate</span></tt> attribute can be applied to functions or parameters.
+When applied to a function the attribute specifies the state of the returned
+value.  The function’s body is checked to ensure that it always returns a value
+in the specified state.  On the caller side, values returned by the annotated
+function are initialized to the given state.</p>
+<p>When applied to a function parameter it modifies the state of an argument after
+a call to the function returns.  The function’s body is checked to ensure that
+the parameter is in the expected state before returning.</p>
+</div>
+<div class="section" id="set-typestate">
+<h3><a class="toc-backref" href="#id109">set_typestate</a><a class="headerlink" href="#set-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Annotate methods that transition an object into a new state with
+<tt class="docutils literal"><span class="pre">__attribute__((set_typestate(new_state)))</span></tt>.  The new state must be
+unconsumed, consumed, or unknown.</p>
+</div>
+<div class="section" id="test-typestate">
+<h3><a class="toc-backref" href="#id110">test_typestate</a><a class="headerlink" href="#test-typestate" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((test_typestate(tested_state)))</span></tt> to indicate that a method
+returns true if the object is in the specified state..</p>
+</div>
+</div>
+<div class="section" id="opencl-address-spaces">
+<h2><a class="toc-backref" href="#id111">OpenCL Address Spaces</a><a class="headerlink" href="#opencl-address-spaces" title="Permalink to this headline">¶</a></h2>
+<p>The address space qualifier may be used to specify the region of memory that is
+used to allocate the object. OpenCL supports the following address spaces:
+__generic(generic), __global(global), __local(local), __private(private),
+__constant(constant).</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="n">__constant</span> <span class="kt">int</span> <span class="n">c</span> <span class="o">=</span> <span class="p">...;</span>
+
+<span class="n">__generic</span> <span class="kt">int</span><span class="o">*</span> <span class="nf">foo</span><span class="p">(</span><span class="n">global</span> <span class="kt">int</span><span class="o">*</span> <span class="n">g</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">__local</span> <span class="kt">int</span><span class="o">*</span> <span class="n">l</span><span class="p">;</span>
+  <span class="n">private</span> <span class="kt">int</span> <span class="n">p</span><span class="p">;</span>
+  <span class="p">...</span>
+  <span class="k">return</span> <span class="n">l</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>More details can be found in the OpenCL C language Spec v2.0, Section 6.5.</p>
+<div class="section" id="constant-constant">
+<h3><a class="toc-backref" href="#id112">constant (__constant)</a><a class="headerlink" href="#constant-constant" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The constant address space attribute signals that an object is located in
+a constant (non-modifiable) memory region. It is available to all work items.
+Any type can be annotated with the constant address space attribute. Objects
+with the constant address space qualifier can be declared in any scope and must
+have an initializer.</p>
+</div>
+<div class="section" id="generic-generic">
+<h3><a class="toc-backref" href="#id113">generic (__generic)</a><a class="headerlink" href="#generic-generic" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The generic address space attribute is only available with OpenCL v2.0 and later.
+It can be used with pointer types. Variables in global and local scope and
+function parameters in non-kernel functions can have the generic address space
+type attribute. It is intended to be a placeholder for any other address space
+except for ‘__constant’ in OpenCL code which can be used with multiple address
+spaces.</p>
+</div>
+<div class="section" id="global-global">
+<h3><a class="toc-backref" href="#id114">global (__global)</a><a class="headerlink" href="#global-global" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The global address space attribute specifies that an object is allocated in
+global memory, which is accessible by all work items. The content stored in this
+memory area persists between kernel executions. Pointer types to the global
+address space are allowed as function parameters or local variables. Starting
+with OpenCL v2.0, the global address space can be used with global (program
+scope) variables and static local variable as well.</p>
+</div>
+<div class="section" id="local-local">
+<h3><a class="toc-backref" href="#id115">local (__local)</a><a class="headerlink" href="#local-local" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The local address space specifies that an object is allocated in the local (work
+group) memory area, which is accessible to all work items in the same work
+group. The content stored in this memory region is not accessible after
+the kernel execution ends. In a kernel function scope, any variable can be in
+the local address space. In other scopes, only pointer types to the local address
+space are allowed. Local address space variables cannot have an initializer.</p>
+</div>
+<div class="section" id="private-private">
+<h3><a class="toc-backref" href="#id116">private (__private)</a><a class="headerlink" href="#private-private" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The private address space specifies that an object is allocated in the private
+(work item) memory. Other work items cannot access the same memory area and its
+content is destroyed after work item execution ends. Local variables can be
+declared in the private address space. Function arguments are always in the
+private address space. Kernel function arguments of a pointer or an array type
+cannot point to the private address space.</p>
+</div>
+</div>
+<div class="section" id="nullability-attributes">
+<h2><a class="toc-backref" href="#id117">Nullability Attributes</a><a class="headerlink" href="#nullability-attributes" title="Permalink to this headline">¶</a></h2>
+<p>Whether a particular pointer may be “null” is an important concern when working with pointers in the C family of languages. The various nullability attributes indicate whether a particular pointer can be null or not, which makes APIs more expressive and can help static analysis tools identify bugs involving null pointers. Clang supports several kinds of nullability attributes: the <tt class="docutils literal"><span class="pre">nonnull</span></tt> and <tt class="docutils literal"><span class="pre">returns_nonnull</span></tt> attributes indicate which function or method parameters and result types can never be null, while nullability type qualifiers indicate which pointer types can be null (<tt class="docutils literal"><span class="pre">_Nullable</span></tt>) or cannot be null (<tt class="docutils literal"><span class="pre">_Nonnull</span></tt>).</p>
+<p>The nullability (type) qualifiers express whether a value of a given pointer type can be null (the <tt class="docutils literal"><span class="pre">_Nullable</span></tt> qualifier), doesn’t have a defined meaning for null (the <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> qualifier), or for which the purpose of null is unclear (the <tt class="docutils literal"><span class="pre">_Null_unspecified</span></tt> qualifier). Because nullability qualifiers are expressed within the type system, they are more general than the <tt class="docutils literal"><span class="pre">nonnull</span></tt> and <tt class="docutils literal"><span class="pre">returns_nonnull</span></tt> attributes, allowing one to express (for example) a nullable pointer to an array of nonnull pointers. Nullability qualifiers are written to the right of the pointer to which they apply. For example:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="c1">// No meaningful result when 'ptr' is null (here, it happens to be undefined behavior).</span>
+<span class="kt">int</span> <span class="nf">fetch</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nonnull</span> <span class="n">ptr</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="o">*</span><span class="n">ptr</span><span class="p">;</span> <span class="p">}</span>
+
+<span class="c1">// 'ptr' may be null.</span>
+<span class="kt">int</span> <span class="nf">fetch_or_zero</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nullable</span> <span class="n">ptr</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">ptr</span> <span class="o">?</span> <span class="o">*</span><span class="n">ptr</span> <span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="c1">// A nullable pointer to non-null pointers to const characters.</span>
+<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="nf">join_strings</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span> <span class="n">_Nonnull</span> <span class="o">*</span> <span class="n">_Nullable</span> <span class="n">strings</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="n">n</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>In Objective-C, there is an alternate spelling for the nullability qualifiers that can be used in Objective-C methods and properties using context-sensitive, non-underscored keywords. For example:</p>
+<blockquote>
+<div><div class="highlight-objective-c"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">NSView</span> : <span class="nc">NSResponder</span>
+  <span class="o">-</span> <span class="p">(</span><span class="n">nullable</span> <span class="n">NSView</span> <span class="o">*</span><span class="p">)</span><span class="n">ancestorSharedWithView</span><span class="o">:</span><span class="p">(</span><span class="n">nonnull</span> <span class="n">NSView</span> <span class="o">*</span><span class="p">)</span><span class="n">aView</span><span class="p">;</span>
+  <span class="k">@property</span> <span class="p">(</span><span class="n">assign</span><span class="p">,</span> <span class="n">nullable</span><span class="p">)</span> <span class="n">NSView</span> <span class="o">*</span><span class="n">superview</span><span class="p">;</span>
+  <span class="k">@property</span> <span class="p">(</span><span class="n">readonly</span><span class="p">,</span> <span class="n">nonnull</span><span class="p">)</span> <span class="n">NSArray</span> <span class="o">*</span><span class="n">subviews</span><span class="p">;</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+</div></blockquote>
+<div class="section" id="nonnull-gnu-nonnull">
+<h3><a class="toc-backref" href="#id118">nonnull (gnu::nonnull)</a><a class="headerlink" href="#nonnull-gnu-nonnull" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">nonnull</span></tt> attribute indicates that some function parameters must not be null, and can be used in several different ways. It’s original usage (<a class="reference external" href="https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes">from GCC</a>) is as a function (or Objective-C method) attribute that specifies which parameters of the function are nonnull in a comma-separated list. For example:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="nf">my_memcpy</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">)</span>
+                <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Here, the <tt class="docutils literal"><span class="pre">nonnull</span></tt> attribute indicates that parameters 1 and 2
+cannot have a null value. Omitting the parenthesized list of parameter indices means that all parameters of pointer type cannot be null:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="nf">my_memcpy</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">)</span>
+                <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span><span class="p">));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Clang also allows the <tt class="docutils literal"><span class="pre">nonnull</span></tt> attribute to be placed directly on a function (or Objective-C method) parameter, eliminating the need to specify the parameter index ahead of type. For example:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="nf">my_memcpy</span> <span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span><span class="p">)),</span>
+                         <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">nonnull</span><span class="p">)),</span> <span class="kt">size_t</span> <span class="n">len</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Note that the <tt class="docutils literal"><span class="pre">nonnull</span></tt> attribute indicates that passing null to a non-null parameter is undefined behavior, which the optimizer may take advantage of to, e.g., remove null checks. The <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable.</p>
+</div>
+<div class="section" id="returns-nonnull-gnu-returns-nonnull">
+<h3><a class="toc-backref" href="#id119">returns_nonnull (gnu::returns_nonnull)</a><a class="headerlink" href="#returns-nonnull-gnu-returns-nonnull" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>X</td>
+<td>X</td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">returns_nonnull</span></tt> attribute indicates that a particular function (or Objective-C method) always returns a non-null pointer. For example, a particular system <tt class="docutils literal"><span class="pre">malloc</span></tt> might be defined to terminate a process when memory is not available rather than returning a null pointer:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="k">extern</span> <span class="kt">void</span> <span class="o">*</span> <span class="nf">malloc</span> <span class="p">(</span><span class="kt">size_t</span> <span class="n">size</span><span class="p">)</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">returns_nonnull</span><span class="p">));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>The <tt class="docutils literal"><span class="pre">returns_nonnull</span></tt> attribute implies that returning a null pointer is undefined behavior, which the optimizer may take advantage of. The <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> type qualifier indicates that a pointer cannot be null in a more general manner (because it is part of the type system) and does not imply undefined behavior, making it more widely applicable</p>
+</div>
+<div class="section" id="nonnull">
+<h3><a class="toc-backref" href="#id120">_Nonnull</a><a class="headerlink" href="#nonnull" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> nullability qualifier indicates that null is not a meaningful value for a value of the <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> pointer type. For example, given a declaration such as:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">fetch</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nonnull</span> <span class="n">ptr</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>a caller of <tt class="docutils literal"><span class="pre">fetch</span></tt> should not provide a null value, and the compiler will produce a warning if it sees a literal null value passed to <tt class="docutils literal"><span class="pre">fetch</span></tt>. Note that, unlike the declaration attribute <tt class="docutils literal"><span class="pre">nonnull</span></tt>, the presence of <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> does not imply that passing null is undefined behavior: <tt class="docutils literal"><span class="pre">fetch</span></tt> is free to consider null undefined behavior or (perhaps for backward-compatibility reasons) defensively handle null.</p>
+</div>
+<div class="section" id="null-unspecified">
+<h3><a class="toc-backref" href="#id121">_Null_unspecified</a><a class="headerlink" href="#null-unspecified" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">_Null_unspecified</span></tt> nullability qualifier indicates that neither the <tt class="docutils literal"><span class="pre">_Nonnull</span></tt> nor <tt class="docutils literal"><span class="pre">_Nullable</span></tt> qualifiers make sense for a particular pointer type. It is used primarily to indicate that the role of null with specific pointers in a nullability-annotated header is unclear, e.g., due to overly-complex implementations or historical factors with a long-lived API.</p>
+</div>
+<div class="section" id="nullable">
+<h3><a class="toc-backref" href="#id122">_Nullable</a><a class="headerlink" href="#nullable" title="Permalink to this headline">¶</a></h3>
+<table border="1" class="docutils">
+<caption>Supported Syntaxes</caption>
+<colgroup>
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">GNU</th>
+<th class="head">C++11</th>
+<th class="head">__declspec</th>
+<th class="head">Keyword</th>
+<th class="head">Pragma</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td> </td>
+<td> </td>
+<td> </td>
+<td>X</td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+<p>The <tt class="docutils literal"><span class="pre">_Nullable</span></tt> nullability qualifier indicates that a value of the <tt class="docutils literal"><span class="pre">_Nullable</span></tt> pointer type can be null. For example, given:</p>
+<blockquote>
+<div><div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">fetch_or_zero</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span> <span class="n">_Nullable</span> <span class="n">ptr</span><span class="p">);</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>a caller of <tt class="docutils literal"><span class="pre">fetch_or_zero</span></tt> can provide null.</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DiagnosticsReference.html">Diagnostic flags in Clang</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/AutomaticReferenceCounting.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/AutomaticReferenceCounting.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/AutomaticReferenceCounting.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/AutomaticReferenceCounting.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,2083 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Objective-C Automatic Reference Counting (ARC) — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+    <link rel="next" title="Attributes in Clang" href="AttributeReference.html" />
+    <link rel="prev" title="Block Implementation Specification" href="Block-ABI-Apple.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Objective-C Automatic Reference Counting (ARC)</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="Block-ABI-Apple.html">Block Implementation Specification</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AttributeReference.html">Attributes in Clang</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <style>
+  .arc-term { font-style: italic; font-weight: bold; }
+  .revision { font-style: italic; }
+  .when-revised { font-weight: bold; font-style: normal; }
+
+  /*
+   * Automatic numbering is described in this article:
+   * http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
+   */
+  /*
+   * Automatic numbering for the TOC.
+   * This is wrong from the semantics point of view, since it is an ordered
+   * list, but uses "ul" tag.
+   */
+  div#contents.contents.local ul {
+    counter-reset: toc-section;
+    list-style-type: none;
+  }
+  div#contents.contents.local ul li {
+    counter-increment: toc-section;
+    background: none; // Remove bullets
+  }
+  div#contents.contents.local ul li a.reference:before {
+    content: counters(toc-section, ".") " ";
+  }
+
+  /* Automatic numbering for the body. */
+  body {
+    counter-reset: section subsection subsubsection;
+  }
+  .section h2 {
+    counter-reset: subsection subsubsection;
+    counter-increment: section;
+  }
+  .section h2 a.toc-backref:before {
+    content: counter(section) " ";
+  }
+  .section h3 {
+    counter-reset: subsubsection;
+    counter-increment: subsection;
+  }
+  .section h3 a.toc-backref:before {
+    content: counter(section) "." counter(subsection) " ";
+  }
+  .section h4 {
+    counter-increment: subsubsection;
+  }
+  .section h4 a.toc-backref:before {
+    content: counter(section) "." counter(subsection) "." counter(subsubsection) " ";
+  }
+</style><div class="section" id="objective-c-automatic-reference-counting-arc">
+<h1>Objective-C Automatic Reference Counting (ARC)<a class="headerlink" href="#objective-c-automatic-reference-counting-arc" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#about-this-document" id="id4">About this document</a><ul>
+<li><a class="reference internal" href="#purpose" id="id5">Purpose</a></li>
+<li><a class="reference internal" href="#background" id="id6">Background</a></li>
+<li><a class="reference internal" href="#evolution" id="id7">Evolution</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#general" id="id8">General</a></li>
+<li><a class="reference internal" href="#retainable-object-pointers" id="id9">Retainable object pointers</a><ul>
+<li><a class="reference internal" href="#retain-count-semantics" id="id10">Retain count semantics</a></li>
+<li><a class="reference internal" href="#retainable-object-pointers-as-operands-and-arguments" id="id11">Retainable object pointers as operands and arguments</a><ul>
+<li><a class="reference internal" href="#consumed-parameters" id="id12">Consumed parameters</a></li>
+<li><a class="reference internal" href="#retained-return-values" id="id13">Retained return values</a></li>
+<li><a class="reference internal" href="#unretained-return-values" id="id14">Unretained return values</a></li>
+<li><a class="reference internal" href="#bridged-casts" id="id15">Bridged casts</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#restrictions" id="id16">Restrictions</a><ul>
+<li><a class="reference internal" href="#conversion-of-retainable-object-pointers" id="id17">Conversion of retainable object pointers</a></li>
+<li><a class="reference internal" href="#conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics" id="id18">Conversion to retainable object pointer type of expressions with known semantics</a></li>
+<li><a class="reference internal" href="#conversion-from-retainable-object-pointer-type-in-certain-contexts" id="id19">Conversion from retainable object pointer type in certain contexts</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ownership-qualification" id="id20">Ownership qualification</a><ul>
+<li><a class="reference internal" href="#spelling" id="id21">Spelling</a><ul>
+<li><a class="reference internal" href="#property-declarations" id="id22">Property declarations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#semantics" id="id23">Semantics</a></li>
+<li><a class="reference internal" href="#arc-ownership-restrictions" id="id24">Restrictions</a><ul>
+<li><a class="reference internal" href="#weak-unavailable-types" id="id25">Weak-unavailable types</a></li>
+<li><a class="reference internal" href="#storage-duration-of-autoreleasing-objects" id="id26">Storage duration of <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> objects</a></li>
+<li><a class="reference internal" href="#conversion-of-pointers-to-ownership-qualified-types" id="id27">Conversion of pointers to ownership-qualified types</a></li>
+<li><a class="reference internal" href="#passing-to-an-out-parameter-by-writeback" id="id28">Passing to an out parameter by writeback</a></li>
+<li><a class="reference internal" href="#ownership-qualified-fields-of-structs-and-unions" id="id29">Ownership-qualified fields of structs and unions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ownership-inference" id="id30">Ownership inference</a><ul>
+<li><a class="reference internal" href="#objects" id="id31">Objects</a></li>
+<li><a class="reference internal" href="#indirect-parameters" id="id32">Indirect parameters</a></li>
+<li><a class="reference internal" href="#template-arguments" id="id33">Template arguments</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#method-families" id="id34">Method families</a><ul>
+<li><a class="reference internal" href="#explicit-method-family-control" id="id35">Explicit method family control</a></li>
+<li><a class="reference internal" href="#semantics-of-method-families" id="id36">Semantics of method families</a><ul>
+<li><a class="reference internal" href="#semantics-of-init" id="id37">Semantics of <tt class="docutils literal"><span class="pre">init</span></tt></a></li>
+<li><a class="reference internal" href="#related-result-types" id="id38">Related result types</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#optimization" id="id39">Optimization</a><ul>
+<li><a class="reference internal" href="#object-liveness" id="id40">Object liveness</a></li>
+<li><a class="reference internal" href="#no-object-lifetime-extension" id="id41">No object lifetime extension</a></li>
+<li><a class="reference internal" href="#precise-lifetime-semantics" id="id42">Precise lifetime semantics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#miscellaneous" id="id43">Miscellaneous</a><ul>
+<li><a class="reference internal" href="#special-methods" id="id44">Special methods</a><ul>
+<li><a class="reference internal" href="#memory-management-methods" id="id45">Memory management methods</a></li>
+<li><a class="reference internal" href="#dealloc" id="id46"><tt class="docutils literal"><span class="pre">dealloc</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#autoreleasepool" id="id47"><tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt></a></li>
+<li><a class="reference internal" href="#self" id="id48"><tt class="docutils literal"><span class="pre">self</span></tt></a></li>
+<li><a class="reference internal" href="#fast-enumeration-iteration-variables" id="id49">Fast enumeration iteration variables</a></li>
+<li><a class="reference internal" href="#blocks" id="id50">Blocks</a></li>
+<li><a class="reference internal" href="#exceptions" id="id51">Exceptions</a></li>
+<li><a class="reference internal" href="#interior-pointers" id="id52">Interior pointers</a></li>
+<li><a class="reference internal" href="#c-retainable-pointer-types" id="id53">C retainable pointer types</a><ul>
+<li><a class="reference internal" href="#auditing-of-c-retainable-pointer-interfaces" id="id54">Auditing of C retainable pointer interfaces</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#runtime-support" id="id55">Runtime support</a><ul>
+<li><a class="reference internal" href="#arc-runtime-objc-autorelease" id="id56"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autorelease(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-autoreleasepoolpop-void-pool" id="id57"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_autoreleasePoolPop(void</span> <span class="pre">*pool);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-autoreleasepoolpush-void" id="id58"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">*objc_autoreleasePoolPush(void);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue" id="id59"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-copyweak-id-dest-id-src" id="id60"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_copyWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-destroyweak-id-object" id="id61"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_destroyWeak(id</span> <span class="pre">*object);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-initweak" id="id62"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_initWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-loadweak" id="id63"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeak(id</span> <span class="pre">*object);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-loadweakretained" id="id64"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeakRetained(id</span> <span class="pre">*object);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-moveweak-id-dest-id-src" id="id65"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_moveWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a></li>
+<li><a class="reference internal" href="#void-objc-release-id-value" id="id66"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_release(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retain" id="id67"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retain(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautorelease" id="id68"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutorelease(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautoreleasereturnvalue" id="id69"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainautoreleasedreturnvalue" id="id70"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleasedReturnValue(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-retainblock" id="id71"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainBlock(id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-storestrong" id="id72"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeStrong(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a></li>
+<li><a class="reference internal" href="#arc-runtime-objc-storeweak" id="id73"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="about-this-document">
+<span id="arc-meta"></span><h2><a class="toc-backref" href="#id4">About this document</a><a class="headerlink" href="#about-this-document" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="purpose">
+<span id="arc-meta-purpose"></span><h3><a class="toc-backref" href="#id5">Purpose</a><a class="headerlink" href="#purpose" title="Permalink to this headline">¶</a></h3>
+<p>The first and primary purpose of this document is to serve as a complete
+technical specification of Automatic Reference Counting.  Given a core
+Objective-C compiler and runtime, it should be possible to write a compiler and
+runtime which implements these new semantics.</p>
+<p>The secondary purpose is to act as a rationale for why ARC was designed in this
+way.  This should remain tightly focused on the technical design and should not
+stray into marketing speculation.</p>
+</div>
+<div class="section" id="background">
+<span id="arc-meta-background"></span><h3><a class="toc-backref" href="#id6">Background</a><a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h3>
+<p>This document assumes a basic familiarity with C.</p>
+<p><span class="arc-term">Blocks</span> are a C language extension for creating anonymous functions.
+Users interact with and transfer block objects using <span class="arc-term">block
+pointers</span>, which are represented like a normal pointer.  A block may capture
+values from local variables; when this occurs, memory must be dynamically
+allocated.  The initial allocation is done on the stack, but the runtime
+provides a <tt class="docutils literal"><span class="pre">Block_copy</span></tt> function which, given a block pointer, either copies
+the underlying block object to the heap, setting its reference count to 1 and
+returning the new block pointer, or (if the block object is already on the
+heap) increases its reference count by 1.  The paired function is
+<tt class="docutils literal"><span class="pre">Block_release</span></tt>, which decreases the reference count by 1 and destroys the
+object if the count reaches zero and is on the heap.</p>
+<p>Objective-C is a set of language extensions, significant enough to be
+considered a different language.  It is a strict superset of C.  The extensions
+can also be imposed on C++, producing a language called Objective-C++.  The
+primary feature is a single-inheritance object system; we briefly describe the
+modern dialect.</p>
+<p>Objective-C defines a new type kind, collectively called the <span class="arc-term">object
+pointer types</span>.  This kind has two notable builtin members, <tt class="docutils literal"><span class="pre">id</span></tt> and
+<tt class="docutils literal"><span class="pre">Class</span></tt>; <tt class="docutils literal"><span class="pre">id</span></tt> is the final supertype of all object pointers.  The validity
+of conversions between object pointer types is not checked at runtime.  Users
+may define <span class="arc-term">classes</span>; each class is a type, and the pointer to that
+type is an object pointer type.  A class may have a superclass; its pointer
+type is a subtype of its superclass’s pointer type.  A class has a set of
+<span class="arc-term">ivars</span>, fields which appear on all instances of that class.  For
+every class <em>T</em> there’s an associated metaclass; it has no fields, its
+superclass is the metaclass of <em>T</em>‘s superclass, and its metaclass is a global
+class.  Every class has a global object whose class is the class’s metaclass;
+metaclasses have no associated type, so pointers to this object have type
+<tt class="docutils literal"><span class="pre">Class</span></tt>.</p>
+<p>A class declaration (<tt class="docutils literal"><span class="pre">@interface</span></tt>) declares a set of <span class="arc-term">methods</span>.  A
+method has a return type, a list of argument types, and a <span class="arc-term">selector</span>:
+a name like <tt class="docutils literal"><span class="pre">foo:bar:baz:</span></tt>, where the number of colons corresponds to the
+number of formal arguments.  A method may be an instance method, in which case
+it can be invoked on objects of the class, or a class method, in which case it
+can be invoked on objects of the metaclass.  A method may be invoked by
+providing an object (called the <span class="arc-term">receiver</span>) and a list of formal
+arguments interspersed with the selector, like so:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="p">[</span><span class="n">receiver</span> <span class="n">foo</span><span class="o">:</span> <span class="n">fooArg</span> <span class="n">bar</span><span class="o">:</span> <span class="n">barArg</span> <span class="n">baz</span><span class="o">:</span> <span class="n">bazArg</span><span class="p">]</span>
+</pre></div>
+</div>
+<p>This looks in the dynamic class of the receiver for a method with this name,
+then in that class’s superclass, etc., until it finds something it can execute.
+The receiver “expression” may also be the name of a class, in which case the
+actual receiver is the class object for that class, or (within method
+definitions) it may be <tt class="docutils literal"><span class="pre">super</span></tt>, in which case the lookup algorithm starts
+with the static superclass instead of the dynamic class.  The actual methods
+dynamically found in a class are not those declared in the <tt class="docutils literal"><span class="pre">@interface</span></tt>, but
+those defined in a separate <tt class="docutils literal"><span class="pre">@implementation</span></tt> declaration; however, when
+compiling a call, typechecking is done based on the methods declared in the
+<tt class="docutils literal"><span class="pre">@interface</span></tt>.</p>
+<p>Method declarations may also be grouped into <span class="arc-term">protocols</span>, which are not
+inherently associated with any class, but which classes may claim to follow.
+Object pointer types may be qualified with additional protocols that the object
+is known to support.</p>
+<p><span class="arc-term">Class extensions</span> are collections of ivars and methods, designed to
+allow a class’s <tt class="docutils literal"><span class="pre">@interface</span></tt> to be split across multiple files; however,
+there is still a primary implementation file which must see the
+<tt class="docutils literal"><span class="pre">@interface</span></tt>s of all class extensions.  <span class="arc-term">Categories</span> allow
+methods (but not ivars) to be declared <em>post hoc</em> on an arbitrary class; the
+methods in the category’s <tt class="docutils literal"><span class="pre">@implementation</span></tt> will be dynamically added to that
+class’s method tables which the category is loaded at runtime, replacing those
+methods in case of a collision.</p>
+<p>In the standard environment, objects are allocated on the heap, and their
+lifetime is manually managed using a reference count.  This is done using two
+instance methods which all classes are expected to implement: <tt class="docutils literal"><span class="pre">retain</span></tt>
+increases the object’s reference count by 1, whereas <tt class="docutils literal"><span class="pre">release</span></tt> decreases it
+by 1 and calls the instance method <tt class="docutils literal"><span class="pre">dealloc</span></tt> if the count reaches 0.  To
+simplify certain operations, there is also an <span class="arc-term">autorelease pool</span>, a
+thread-local list of objects to call <tt class="docutils literal"><span class="pre">release</span></tt> on later; an object can be
+added to this pool by calling <tt class="docutils literal"><span class="pre">autorelease</span></tt> on it.</p>
+<p>Block pointers may be converted to type <tt class="docutils literal"><span class="pre">id</span></tt>; block objects are laid out in a
+way that makes them compatible with Objective-C objects.  There is a builtin
+class that all block objects are considered to be objects of; this class
+implements <tt class="docutils literal"><span class="pre">retain</span></tt> by adjusting the reference count, not by calling
+<tt class="docutils literal"><span class="pre">Block_copy</span></tt>.</p>
+</div>
+<div class="section" id="evolution">
+<span id="arc-meta-evolution"></span><h3><a class="toc-backref" href="#id7">Evolution</a><a class="headerlink" href="#evolution" title="Permalink to this headline">¶</a></h3>
+<p>ARC is under continual evolution, and this document must be updated as the
+language progresses.</p>
+<p>If a change increases the expressiveness of the language, for example by
+lifting a restriction or by adding new syntax, the change will be annotated
+with a revision marker, like so:</p>
+<blockquote>
+<div>ARC applies to Objective-C pointer types, block pointer types, and
+<span class="when-revised">[beginning Apple 8.0, LLVM 3.8]</span> <span class="revision">BPTRs declared
+within</span> <tt class="docutils literal"><span class="pre">extern</span> <span class="pre">"BCPL"</span></tt> blocks.</div></blockquote>
+<p>For now, it is sensible to version this document by the releases of its sole
+implementation (and its host project), clang.  “LLVM X.Y” refers to an
+open-source release of clang from the LLVM project.  “Apple X.Y” refers to an
+Apple-provided release of the Apple LLVM Compiler.  Other organizations that
+prepare their own, separately-versioned clang releases and wish to maintain
+similar information in this document should send requests to cfe-dev.</p>
+<p>If a change decreases the expressiveness of the language, for example by
+imposing a new restriction, this should be taken as an oversight in the
+original specification and something to be avoided in all versions.  Such
+changes are generally to be avoided.</p>
+</div>
+</div>
+<div class="section" id="general">
+<span id="arc-general"></span><h2><a class="toc-backref" href="#id8">General</a><a class="headerlink" href="#general" title="Permalink to this headline">¶</a></h2>
+<p>Automatic Reference Counting implements automatic memory management for
+Objective-C objects and blocks, freeing the programmer from the need to
+explicitly insert retains and releases.  It does not provide a cycle collector;
+users must explicitly manage the lifetime of their objects, breaking cycles
+manually or with weak or unsafe references.</p>
+<p>ARC may be explicitly enabled with the compiler flag <tt class="docutils literal"><span class="pre">-fobjc-arc</span></tt>.  It may
+also be explicitly disabled with the compiler flag <tt class="docutils literal"><span class="pre">-fno-objc-arc</span></tt>.  The last
+of these two flags appearing on the compile line “wins”.</p>
+<p>If ARC is enabled, <tt class="docutils literal"><span class="pre">__has_feature(objc_arc)</span></tt> will expand to 1 in the
+preprocessor.  For more information about <tt class="docutils literal"><span class="pre">__has_feature</span></tt>, see the
+<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><em>language extensions</em></a> document.</p>
+</div>
+<div class="section" id="retainable-object-pointers">
+<span id="arc-objects"></span><h2><a class="toc-backref" href="#id9">Retainable object pointers</a><a class="headerlink" href="#retainable-object-pointers" title="Permalink to this headline">¶</a></h2>
+<p>This section describes retainable object pointers, their basic operations, and
+the restrictions imposed on their use under ARC.  Note in particular that it
+covers the rules for pointer <em>values</em> (patterns of bits indicating the location
+of a pointed-to object), not pointer <em>objects</em> (locations in memory which store
+pointer values).  The rules for objects are covered in the next section.</p>
+<p>A <span class="arc-term">retainable object pointer</span> (or “retainable pointer”) is a value of
+a <span class="arc-term">retainable object pointer type</span> (“retainable type”).  There are
+three kinds of retainable object pointer types:</p>
+<ul class="simple">
+<li>block pointers (formed by applying the caret (<tt class="docutils literal"><span class="pre">^</span></tt>) declarator sigil to a
+function type)</li>
+<li>Objective-C object pointers (<tt class="docutils literal"><span class="pre">id</span></tt>, <tt class="docutils literal"><span class="pre">Class</span></tt>, <tt class="docutils literal"><span class="pre">NSFoo*</span></tt>, etc.)</li>
+<li>typedefs marked with <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt></li>
+</ul>
+<p>Other pointer types, such as <tt class="docutils literal"><span class="pre">int*</span></tt> and <tt class="docutils literal"><span class="pre">CFStringRef</span></tt>, are not subject to
+ARC’s semantics and restrictions.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>We are not at liberty to require all code to be recompiled with ARC;
+therefore, ARC must interoperate with Objective-C code which manages retains
+and releases manually.  In general, there are three requirements in order for
+a compiler-supported reference-count system to provide reliable
+interoperation:</p>
+<ul class="last simple">
+<li>The type system must reliably identify which objects are to be managed.  An
+<tt class="docutils literal"><span class="pre">int*</span></tt> might be a pointer to a <tt class="docutils literal"><span class="pre">malloc</span></tt>‘ed array, or it might be an
+interior pointer to such an array, or it might point to some field or local
+variable.  In contrast, values of the retainable object pointer types are
+never interior.</li>
+<li>The type system must reliably indicate how to manage objects of a type.
+This usually means that the type must imply a procedure for incrementing
+and decrementing retain counts.  Supporting single-ownership objects
+requires a lot more explicit mediation in the language.</li>
+<li>There must be reliable conventions for whether and when “ownership” is
+passed between caller and callee, for both arguments and return values.
+Objective-C methods follow such a convention very reliably, at least for
+system libraries on Mac OS X, and functions always pass objects at +0.  The
+C-based APIs for Core Foundation objects, on the other hand, have much more
+varied transfer semantics.</li>
+</ul>
+</div>
+<p>The use of <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> typedefs is not recommended.  If it’s
+absolutely necessary to use this attribute, be very explicit about using the
+typedef, and do not assume that it will be preserved by language features like
+<tt class="docutils literal"><span class="pre">__typeof</span></tt> and C++ template argument substitution.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Any compiler operation which incidentally strips type “sugar” from a type
+will yield a type without the attribute, which may result in unexpected
+behavior.</p>
+</div>
+<div class="section" id="retain-count-semantics">
+<span id="arc-objects-retains"></span><h3><a class="toc-backref" href="#id10">Retain count semantics</a><a class="headerlink" href="#retain-count-semantics" title="Permalink to this headline">¶</a></h3>
+<p>A retainable object pointer is either a <span class="arc-term">null pointer</span> or a pointer
+to a valid object.  Furthermore, if it has block pointer type and is not
+<tt class="docutils literal"><span class="pre">null</span></tt> then it must actually be a pointer to a block object, and if it has
+<tt class="docutils literal"><span class="pre">Class</span></tt> type (possibly protocol-qualified) then it must actually be a pointer
+to a class object.  Otherwise ARC does not enforce the Objective-C type system
+as long as the implementing methods follow the signature of the static type.
+It is undefined behavior if ARC is exposed to an invalid pointer.</p>
+<p>For ARC’s purposes, a valid object is one with “well-behaved” retaining
+operations.  Specifically, the object must be laid out such that the
+Objective-C message send machinery can successfully send it the following
+messages:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">retain</span></tt>, taking no arguments and returning a pointer to the object.</li>
+<li><tt class="docutils literal"><span class="pre">release</span></tt>, taking no arguments and returning <tt class="docutils literal"><span class="pre">void</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">autorelease</span></tt>, taking no arguments and returning a pointer to the object.</li>
+</ul>
+<p>The behavior of these methods is constrained in the following ways.  The term
+<span class="arc-term">high-level semantics</span> is an intentionally vague term; the intent is
+that programmers must implement these methods in a way such that the compiler,
+modifying code in ways it deems safe according to these constraints, will not
+violate their requirements.  For example, if the user puts logging statements
+in <tt class="docutils literal"><span class="pre">retain</span></tt>, they should not be surprised if those statements are executed
+more or less often depending on optimization settings.  These constraints are
+not exhaustive of the optimization opportunities: values held in local
+variables are subject to additional restrictions, described later in this
+document.</p>
+<p>It is undefined behavior if a computation history featuring a send of
+<tt class="docutils literal"><span class="pre">retain</span></tt> followed by a send of <tt class="docutils literal"><span class="pre">release</span></tt> to the same object, with no
+intervening <tt class="docutils literal"><span class="pre">release</span></tt> on that object, is not equivalent under the high-level
+semantics to a computation history in which these sends are removed.  Note that
+this implies that these methods may not raise exceptions.</p>
+<p>It is undefined behavior if a computation history features any use whatsoever
+of an object following the completion of a send of <tt class="docutils literal"><span class="pre">release</span></tt> that is not
+preceded by a send of <tt class="docutils literal"><span class="pre">retain</span></tt> to the same object.</p>
+<p>The behavior of <tt class="docutils literal"><span class="pre">autorelease</span></tt> must be equivalent to sending <tt class="docutils literal"><span class="pre">release</span></tt> when
+one of the autorelease pools currently in scope is popped.  It may not throw an
+exception.</p>
+<p>When the semantics call for performing one of these operations on a retainable
+object pointer, if that pointer is <tt class="docutils literal"><span class="pre">null</span></tt> then the effect is a no-op.</p>
+<p>All of the semantics described in this document are subject to additional
+<a class="reference internal" href="#arc-optimization"><em>optimization rules</em></a> which permit the removal or
+optimization of operations based on local knowledge of data flow.  The
+semantics describe the high-level behaviors that the compiler implements, not
+an exact sequence of operations that a program will be compiled into.</p>
+</div>
+<div class="section" id="retainable-object-pointers-as-operands-and-arguments">
+<span id="arc-objects-operands"></span><h3><a class="toc-backref" href="#id11">Retainable object pointers as operands and arguments</a><a class="headerlink" href="#retainable-object-pointers-as-operands-and-arguments" title="Permalink to this headline">¶</a></h3>
+<p>In general, ARC does not perform retain or release operations when simply using
+a retainable object pointer as an operand within an expression.  This includes:</p>
+<ul class="simple">
+<li>loading a retainable pointer from an object with non-weak <a class="reference internal" href="#arc-ownership"><em>ownership</em></a>,</li>
+<li>passing a retainable pointer as an argument to a function or method, and</li>
+<li>receiving a retainable pointer as the result of a function or method call.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">While this might seem uncontroversial, it is actually unsafe when multiple
+expressions are evaluated in “parallel”, as with binary operators and calls,
+because (for example) one expression might load from an object while another
+writes to it.  However, C and C++ already call this undefined behavior
+because the evaluations are unsequenced, and ARC simply exploits that here to
+avoid needing to retain arguments across a large number of calls.</p>
+</div>
+<p>The remainder of this section describes exceptions to these rules, how those
+exceptions are detected, and what those exceptions imply semantically.</p>
+<div class="section" id="consumed-parameters">
+<span id="arc-objects-operands-consumed"></span><h4><a class="toc-backref" href="#id12">Consumed parameters</a><a class="headerlink" href="#consumed-parameters" title="Permalink to this headline">¶</a></h4>
+<p>A function or method parameter of retainable object pointer type may be marked
+as <span class="arc-term">consumed</span>, signifying that the callee expects to take ownership
+of a +1 retain count.  This is done by adding the <tt class="docutils literal"><span class="pre">ns_consumed</span></tt> attribute to
+the parameter declaration, like so:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="n">__attribute</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="kt">id</span> <span class="n">x</span><span class="p">);</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="nf">foo:</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_consumed</span><span class="p">))</span> <span class="n">x</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This attribute is part of the type of the function or method, not the type of
+the parameter.  It controls only how the argument is passed and received.</p>
+<p>When passing such an argument, ARC retains the argument prior to making the
+call.</p>
+<p>When receiving such an argument, ARC releases the argument at the end of the
+function, subject to the usual optimizations for local values.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This formalizes direct transfers of ownership from a caller to a callee.  The
+most common scenario here is passing the <tt class="docutils literal"><span class="pre">self</span></tt> parameter to <tt class="docutils literal"><span class="pre">init</span></tt>, but
+it is useful to generalize.  Typically, local optimization will remove any
+extra retains and releases: on the caller side the retain will be merged with
+a +1 source, and on the callee side the release will be rolled into the
+initialization of the parameter.</p>
+</div>
+<p>The implicit <tt class="docutils literal"><span class="pre">self</span></tt> parameter of a method may be marked as consumed by adding
+<tt class="docutils literal"><span class="pre">__attribute__((ns_consumes_self))</span></tt> to the method declaration.  Methods in
+the <tt class="docutils literal"><span class="pre">init</span></tt> <a class="reference internal" href="#arc-method-families"><em>family</em></a> are treated as if they were
+implicitly marked with this attribute.</p>
+<p>It is undefined behavior if an Objective-C message send to a method with
+<tt class="docutils literal"><span class="pre">ns_consumed</span></tt> parameters (other than self) is made with a null receiver.  It
+is undefined behavior if the method to which an Objective-C message send
+statically resolves to has a different set of <tt class="docutils literal"><span class="pre">ns_consumed</span></tt> parameters than
+the method it dynamically resolves to.  It is undefined behavior if a block or
+function call is made through a static type with a different set of
+<tt class="docutils literal"><span class="pre">ns_consumed</span></tt> parameters than the implementation of the called block or
+function.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Consumed parameters with null receiver are a guaranteed leak.  Mismatches
+with consumed parameters will cause over-retains or over-releases, depending
+on the direction.  The rule about function calls is really just an
+application of the existing C/C++ rule about calling functions through an
+incompatible function type, but it’s useful to state it explicitly.</p>
+</div>
+</div>
+<div class="section" id="retained-return-values">
+<span id="arc-object-operands-retained-return-values"></span><h4><a class="toc-backref" href="#id13">Retained return values</a><a class="headerlink" href="#retained-return-values" title="Permalink to this headline">¶</a></h4>
+<p>A function or method which returns a retainable object pointer type may be
+marked as returning a retained value, signifying that the caller expects to take
+ownership of a +1 retain count.  This is done by adding the
+<tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt> attribute to the function or method declaration, like
+so:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
+<span class="k">-</span> <span class="p">(</span><span class="kt">id</span><span class="p">)</span> <span class="nf">foo</span> <span class="n">__attribute</span><span class="p">((</span><span class="n">ns_returns_retained</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This attribute is part of the type of the function or method.</p>
+<p>When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, before leaving all local scopes.</p>
+<p>When receiving a return result from such a function or method, ARC releases the
+value at the end of the full-expression it is contained within, subject to the
+usual optimizations for local values.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This formalizes direct transfers of ownership from a callee to a caller.  The
+most common scenario this models is the retained return from <tt class="docutils literal"><span class="pre">init</span></tt>,
+<tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">new</span></tt>, and <tt class="docutils literal"><span class="pre">copy</span></tt> methods, but there are other cases in the
+frameworks.  After optimization there are typically no extra retains and
+releases required.</p>
+</div>
+<p>Methods in the <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">init</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, and <tt class="docutils literal"><span class="pre">new</span></tt>
+<a class="reference internal" href="#arc-method-families"><em>families</em></a> are implicitly marked
+<tt class="docutils literal"><span class="pre">__attribute__((ns_returns_retained))</span></tt>.  This may be suppressed by explicitly
+marking the method <tt class="docutils literal"><span class="pre">__attribute__((ns_returns_not_retained))</span></tt>.</p>
+<p>It is undefined behavior if the method to which an Objective-C message send
+statically resolves has different retain semantics on its result from the
+method it dynamically resolves to.  It is undefined behavior if a block or
+function call is made through a static type with different retain semantics on
+its result from the implementation of the called block or function.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Mismatches with returned results will cause over-retains or over-releases,
+depending on the direction.  Again, the rule about function calls is really
+just an application of the existing C/C++ rule about calling functions
+through an incompatible function type.</p>
+</div>
+</div>
+<div class="section" id="unretained-return-values">
+<span id="arc-objects-operands-unretained-returns"></span><h4><a class="toc-backref" href="#id14">Unretained return values</a><a class="headerlink" href="#unretained-return-values" title="Permalink to this headline">¶</a></h4>
+<p>A method or function which returns a retainable object type but does not return
+a retained value must ensure that the object is still valid across the return
+boundary.</p>
+<p>When returning from such a function or method, ARC retains the value at the
+point of evaluation of the return statement, then leaves all local scopes, and
+then balances out the retain while ensuring that the value lives across the
+call boundary.  In the worst case, this may involve an <tt class="docutils literal"><span class="pre">autorelease</span></tt>, but
+callers must not assume that the value is actually in the autorelease pool.</p>
+<p>ARC performs no extra mandatory work on the caller side, although it may elect
+to do something to shorten the lifetime of the returned value.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">It is common in non-ARC code to not return an autoreleased value; therefore
+the convention does not force either path.  It is convenient to not be
+required to do unnecessary retains and autoreleases; this permits
+optimizations such as eliding retain/autoreleases when it can be shown that
+the original pointer will still be valid at the point of return.</p>
+</div>
+<p>A method or function may be marked with
+<tt class="docutils literal"><span class="pre">__attribute__((ns_returns_autoreleased))</span></tt> to indicate that it returns a
+pointer which is guaranteed to be valid at least as long as the innermost
+autorelease pool.  There are no additional semantics enforced in the definition
+of such a method; it merely enables optimizations in callers.</p>
+</div>
+<div class="section" id="bridged-casts">
+<span id="arc-objects-operands-casts"></span><h4><a class="toc-backref" href="#id15">Bridged casts</a><a class="headerlink" href="#bridged-casts" title="Permalink to this headline">¶</a></h4>
+<p>A <span class="arc-term">bridged cast</span> is a C-style cast annotated with one of three
+keywords:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">(__bridge</span> <span class="pre">T)</span> <span class="pre">op</span></tt> casts the operand to the destination type <tt class="docutils literal"><span class="pre">T</span></tt>.  If
+<tt class="docutils literal"><span class="pre">T</span></tt> is a retainable object pointer type, then <tt class="docutils literal"><span class="pre">op</span></tt> must have a
+non-retainable pointer type.  If <tt class="docutils literal"><span class="pre">T</span></tt> is a non-retainable pointer type,
+then <tt class="docutils literal"><span class="pre">op</span></tt> must have a retainable object pointer type.  Otherwise the cast
+is ill-formed.  There is no transfer of ownership, and ARC inserts no retain
+operations.</li>
+<li><tt class="docutils literal"><span class="pre">(__bridge_retained</span> <span class="pre">T)</span> <span class="pre">op</span></tt> casts the operand, which must have retainable
+object pointer type, to the destination type, which must be a non-retainable
+pointer type.  ARC retains the value, subject to the usual optimizations on
+local values, and the recipient is responsible for balancing that +1.</li>
+<li><tt class="docutils literal"><span class="pre">(__bridge_transfer</span> <span class="pre">T)</span> <span class="pre">op</span></tt> casts the operand, which must have
+non-retainable pointer type, to the destination type, which must be a
+retainable object pointer type.  ARC will release the value at the end of
+the enclosing full-expression, subject to the usual optimizations on local
+values.</li>
+</ul>
+<p>These casts are required in order to transfer objects in and out of ARC
+control; see the rationale in the section on <a class="reference internal" href="#arc-objects-restrictions-conversion"><em>conversion of retainable
+object pointers</em></a>.</p>
+<p>Using a <tt class="docutils literal"><span class="pre">__bridge_retained</span></tt> or <tt class="docutils literal"><span class="pre">__bridge_transfer</span></tt> cast purely to convince
+ARC to emit an unbalanced retain or release, respectively, is poor form.</p>
+</div>
+</div>
+<div class="section" id="restrictions">
+<span id="arc-objects-restrictions"></span><h3><a class="toc-backref" href="#id16">Restrictions</a><a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="conversion-of-retainable-object-pointers">
+<span id="arc-objects-restrictions-conversion"></span><h4><a class="toc-backref" href="#id17">Conversion of retainable object pointers</a><a class="headerlink" href="#conversion-of-retainable-object-pointers" title="Permalink to this headline">¶</a></h4>
+<p>In general, a program which attempts to implicitly or explicitly convert a
+value of retainable object pointer type to any non-retainable type, or
+vice-versa, is ill-formed.  For example, an Objective-C object pointer shall
+not be converted to <tt class="docutils literal"><span class="pre">void*</span></tt>.  As an exception, cast to <tt class="docutils literal"><span class="pre">intptr_t</span></tt> is
+allowed because such casts are not transferring ownership.  The <a class="reference internal" href="#arc-objects-operands-casts"><em>bridged
+casts</em></a> may be used to perform these conversions
+where necessary.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">We cannot ensure the correct management of the lifetime of objects if they
+may be freely passed around as unmanaged types.  The bridged casts are
+provided so that the programmer may explicitly describe whether the cast
+transfers control into or out of ARC.</p>
+</div>
+<p>However, the following exceptions apply.</p>
+</div>
+<div class="section" id="conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics">
+<span id="arc-objects-restrictions-conversion-with-known-semantics"></span><h4><a class="toc-backref" href="#id18">Conversion to retainable object pointer type of expressions with known semantics</a><a class="headerlink" href="#conversion-to-retainable-object-pointer-type-of-expressions-with-known-semantics" title="Permalink to this headline">¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span>
+<span class="revision">These exceptions have been greatly expanded; they previously applied
+only to a much-reduced subset which is difficult to categorize but which
+included null pointers, message sends (under the given rules), and the various
+global constants.</span></p>
+<p>An unbridged conversion to a retainable object pointer type from a type other
+than a retainable object pointer type is ill-formed, as discussed above, unless
+the operand of the cast has a syntactic form which is known retained, known
+unretained, or known retain-agnostic.</p>
+<p>An expression is <span class="arc-term">known retain-agnostic</span> if it is:</p>
+<ul class="simple">
+<li>an Objective-C string literal,</li>
+<li>a load from a <tt class="docutils literal"><span class="pre">const</span></tt> system global variable of <a class="reference internal" href="#arc-misc-c-retainable"><em>C retainable pointer
+type</em></a>, or</li>
+<li>a null pointer constant.</li>
+</ul>
+<p>An expression is <span class="arc-term">known unretained</span> if it is an rvalue of <a class="reference internal" href="#arc-misc-c-retainable"><em>C
+retainable pointer type</em></a> and it is:</p>
+<ul class="simple">
+<li>a direct call to a function, and either that function has the
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt> attribute or it is an <a class="reference internal" href="#arc-misc-c-retainable-audit"><em>audited</em></a> function that does not have the
+<tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> attribute and does not follow the create/copy naming
+convention,</li>
+<li>a message send, and the declared method either has the
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt> attribute or it has neither the
+<tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> attribute nor a <a class="reference internal" href="#arc-method-families"><em>selector family</em></a> that implies a retained result, or</li>
+<li><span class="when-revised">[beginning LLVM 3.6]</span> <span class="revision">a load from a</span> <tt class="docutils literal"><span class="pre">const</span></tt>
+<span class="revision">non-system global variable.</span></li>
+</ul>
+<p>An expression is <span class="arc-term">known retained</span> if it is an rvalue of <a class="reference internal" href="#arc-misc-c-retainable"><em>C
+retainable pointer type</em></a> and it is:</p>
+<ul class="simple">
+<li>a message send, and the declared method either has the
+<tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> attribute, or it does not have the
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt> attribute but it does have a <a class="reference internal" href="#arc-method-families"><em>selector
+family</em></a> that implies a retained result.</li>
+</ul>
+<p>Furthermore:</p>
+<ul class="simple">
+<li>a comma expression is classified according to its right-hand side,</li>
+<li>a statement expression is classified according to its result expression, if
+it has one,</li>
+<li>an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is
+classified according to the underlying message send, and</li>
+<li>a conditional operator is classified according to its second and third
+operands, if they agree in classification, or else the other if one is known
+retain-agnostic.</li>
+</ul>
+<p>If the cast operand is known retained, the conversion is treated as a
+<tt class="docutils literal"><span class="pre">__bridge_transfer</span></tt> cast.  If the cast operand is known unretained or known
+retain-agnostic, the conversion is treated as a <tt class="docutils literal"><span class="pre">__bridge</span></tt> cast.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Bridging casts are annoying.  Absent the ability to completely automate the
+management of CF objects, however, we are left with relatively poor attempts
+to reduce the need for a glut of explicit bridges.  Hence these rules.</p>
+<p>We’ve so far consciously refrained from implicitly turning retained CF
+results from function calls into <tt class="docutils literal"><span class="pre">__bridge_transfer</span></tt> casts.  The worry is
+that some code patterns  —  for example, creating a CF value, assigning it
+to an ObjC-typed local, and then calling <tt class="docutils literal"><span class="pre">CFRelease</span></tt> when done  —  are a
+bit too likely to be accidentally accepted, leading to mysterious behavior.</p>
+<p class="last">For loads from <tt class="docutils literal"><span class="pre">const</span></tt> global variables of <a class="reference internal" href="#arc-misc-c-retainable"><em>C retainable pointer type</em></a>, it is reasonable to assume that global system
+constants were initialitzed with true constants (e.g. string literals), but
+user constants might have been initialized with something dynamically
+allocated, using a global initializer.</p>
+</div>
+</div>
+<div class="section" id="conversion-from-retainable-object-pointer-type-in-certain-contexts">
+<span id="arc-objects-restrictions-conversion-exception-contextual"></span><h4><a class="toc-backref" href="#id19">Conversion from retainable object pointer type in certain contexts</a><a class="headerlink" href="#conversion-from-retainable-object-pointer-type-in-certain-contexts" title="Permalink to this headline">¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span></p>
+<p>If an expression of retainable object pointer type is explicitly cast to a
+<a class="reference internal" href="#arc-misc-c-retainable"><em>C retainable pointer type</em></a>, the program is
+ill-formed as discussed above unless the result is immediately used:</p>
+<ul class="simple">
+<li>to initialize a parameter in an Objective-C message send where the parameter
+is not marked with the <tt class="docutils literal"><span class="pre">cf_consumed</span></tt> attribute, or</li>
+<li>to initialize a parameter in a direct call to an
+<a class="reference internal" href="#arc-misc-c-retainable-audit"><em>audited</em></a> function where the parameter is
+not marked with the <tt class="docutils literal"><span class="pre">cf_consumed</span></tt> attribute.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Consumed parameters are left out because ARC would naturally balance them
+with a retain, which was judged too treacherous.  This is in part because
+several of the most common consuming functions are in the <tt class="docutils literal"><span class="pre">Release</span></tt> family,
+and it would be quite unfortunate for explicit releases to be silently
+balanced out in this way.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="ownership-qualification">
+<span id="arc-ownership"></span><h2><a class="toc-backref" href="#id20">Ownership qualification</a><a class="headerlink" href="#ownership-qualification" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the behavior of <em>objects</em> of retainable object pointer
+type; that is, locations in memory which store retainable object pointers.</p>
+<p>A type is a <span class="arc-term">retainable object owner type</span> if it is a retainable
+object pointer type or an array type whose element type is a retainable object
+owner type.</p>
+<p>An <span class="arc-term">ownership qualifier</span> is a type qualifier which applies only to
+retainable object owner types.  An array type is ownership-qualified according
+to its element type, and adding an ownership qualifier to an array type so
+qualifies its element type.</p>
+<p>A program is ill-formed if it attempts to apply an ownership qualifier to a
+type which is already ownership-qualified, even if it is the same qualifier.
+There is a single exception to this rule: an ownership qualifier may be applied
+to a substituted template type parameter, which overrides the ownership
+qualifier provided by the template argument.</p>
+<p>When forming a function type, the result type is adjusted so that any
+top-level ownership qualifier is deleted.</p>
+<p>Except as described under the <a class="reference internal" href="#arc-ownership-inference"><em>inference rules</em></a>,
+a program is ill-formed if it attempts to form a pointer or reference type to a
+retainable object owner type which lacks an ownership qualifier.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">These rules, together with the inference rules, ensure that all objects and
+lvalues of retainable object pointer type have an ownership qualifier.  The
+ability to override an ownership qualifier during template substitution is
+required to counteract the <a class="reference internal" href="#arc-ownership-inference-template-arguments"><em>inference of __strong for template type
+arguments</em></a>.  Ownership qualifiers
+on return types are dropped because they serve no purpose there except to
+cause spurious problems with overloading and templates.</p>
+</div>
+<p>There are four ownership qualifiers:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">__autoreleasing</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__strong</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">__weak</span></tt></li>
+</ul>
+<p>A type is <span class="arc-term">nontrivially ownership-qualified</span> if it is qualified with
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt>, <tt class="docutils literal"><span class="pre">__strong</span></tt>, or <tt class="docutils literal"><span class="pre">__weak</span></tt>.</p>
+<div class="section" id="spelling">
+<span id="arc-ownership-spelling"></span><h3><a class="toc-backref" href="#id21">Spelling</a><a class="headerlink" href="#spelling" title="Permalink to this headline">¶</a></h3>
+<p>The names of the ownership qualifiers are reserved for the implementation.  A
+program may not assume that they are or are not implemented with macros, or
+what those macros expand to.</p>
+<p>An ownership qualifier may be written anywhere that any other type qualifier
+may be written.</p>
+<p>If an ownership qualifier appears in the <em>declaration-specifiers</em>, the
+following rules apply:</p>
+<ul class="simple">
+<li>if the type specifier is a retainable object owner type, the qualifier
+initially applies to that type;</li>
+<li>otherwise, if the outermost non-array declarator is a pointer
+or block pointer declarator, the qualifier initially applies to
+that type;</li>
+<li>otherwise the program is ill-formed.</li>
+<li>If the qualifier is so applied at a position in the declaration
+where the next-innermost declarator is a function declarator, and
+there is an block declarator within that function declarator, then
+the qualifier applies instead to that block declarator and this rule
+is considered afresh beginning from the new position.</li>
+</ul>
+<p>If an ownership qualifier appears on the declarator name, or on the declared
+object, it is applied to the innermost pointer or block-pointer type.</p>
+<p>If an ownership qualifier appears anywhere else in a declarator, it applies to
+the type there.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Ownership qualifiers are like <tt class="docutils literal"><span class="pre">const</span></tt> and <tt class="docutils literal"><span class="pre">volatile</span></tt> in the sense
+that they may sensibly apply at multiple distinct positions within a
+declarator.  However, unlike those qualifiers, there are many
+situations where they are not meaningful, and so we make an effort
+to “move” the qualifier to a place where it will be meaningful.  The
+general goal is to allow the programmer to write, say, <tt class="docutils literal"><span class="pre">__strong</span></tt>
+before the entire declaration and have it apply in the leftmost
+sensible place.</p>
+</div>
+<div class="section" id="property-declarations">
+<span id="arc-ownership-spelling-property"></span><h4><a class="toc-backref" href="#id22">Property declarations</a><a class="headerlink" href="#property-declarations" title="Permalink to this headline">¶</a></h4>
+<p>A property of retainable object pointer type may have ownership.  If the
+property’s type is ownership-qualified, then the property has that ownership.
+If the property has one of the following modifiers, then the property has the
+corresponding ownership.  A property is ill-formed if it has conflicting
+sources of ownership, or if it has redundant ownership modifiers, or if it has
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> ownership.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">assign</span></tt> implies <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">copy</span></tt> implies <tt class="docutils literal"><span class="pre">__strong</span></tt> ownership, as well as the usual behavior of
+copy semantics on the setter.</li>
+<li><tt class="docutils literal"><span class="pre">retain</span></tt> implies <tt class="docutils literal"><span class="pre">__strong</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">strong</span></tt> implies <tt class="docutils literal"><span class="pre">__strong</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">unsafe_unretained</span></tt> implies <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> ownership.</li>
+<li><tt class="docutils literal"><span class="pre">weak</span></tt> implies <tt class="docutils literal"><span class="pre">__weak</span></tt> ownership.</li>
+</ul>
+<p>With the exception of <tt class="docutils literal"><span class="pre">weak</span></tt>, these modifiers are available in non-ARC
+modes.</p>
+<p>A property’s specified ownership is preserved in its metadata, but otherwise
+the meaning is purely conventional unless the property is synthesized.  If a
+property is synthesized, then the <span class="arc-term">associated instance variable</span> is
+the instance variable which is named, possibly implicitly, by the
+<tt class="docutils literal"><span class="pre">@synthesize</span></tt> declaration.  If the associated instance variable already
+exists, then its ownership qualification must equal the ownership of the
+property; otherwise, the instance variable is created with that ownership
+qualification.</p>
+<p>A property of retainable object pointer type which is synthesized without a
+source of ownership has the ownership of its associated instance variable, if it
+already exists; otherwise, <span class="when-revised">[beginning Apple 3.1, LLVM 3.1]</span>
+<span class="revision">its ownership is implicitly</span> <tt class="docutils literal"><span class="pre">strong</span></tt>.  Prior to this revision, it
+was ill-formed to synthesize such a property.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Using <tt class="docutils literal"><span class="pre">strong</span></tt> by default is safe and consistent with the generic ARC rule
+about <a class="reference internal" href="#arc-ownership-inference-variables"><em>inferring ownership</em></a>.  It is,
+unfortunately, inconsistent with the non-ARC rule which states that such
+properties are implicitly <tt class="docutils literal"><span class="pre">assign</span></tt>.  However, that rule is clearly
+untenable in ARC, since it leads to default-unsafe code.  The main merit to
+banning the properties is to avoid confusion with non-ARC practice, which did
+not ultimately strike us as sufficient to justify requiring extra syntax and
+(more importantly) forcing novices to understand ownership rules just to
+declare a property when the default is so reasonable.  Changing the rule away
+from non-ARC practice was acceptable because we had conservatively banned the
+synthesis in order to give ourselves exactly this leeway.</p>
+</div>
+<p>Applying <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> to a property not of retainable object
+pointer type has the same behavior it does outside of ARC: it requires the
+property type to be some sort of pointer and permits the use of modifiers other
+than <tt class="docutils literal"><span class="pre">assign</span></tt>.  These modifiers only affect the synthesized getter and
+setter; direct accesses to the ivar (even if synthesized) still have primitive
+semantics, and the value in the ivar will not be automatically released during
+deallocation.</p>
+</div>
+</div>
+<div class="section" id="semantics">
+<span id="arc-ownership-semantics"></span><h3><a class="toc-backref" href="#id23">Semantics</a><a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h3>
+<p>There are five <span class="arc-term">managed operations</span> which may be performed on an
+object of retainable object pointer type.  Each qualifier specifies different
+semantics for each of these operations.  It is still undefined behavior to
+access an object outside of its lifetime.</p>
+<p>A load or store with “primitive semantics” has the same semantics as the
+respective operation would have on an <tt class="docutils literal"><span class="pre">void*</span></tt> lvalue with the same alignment
+and non-ownership qualification.</p>
+<p><span class="arc-term">Reading</span> occurs when performing a lvalue-to-rvalue conversion on an
+object lvalue.</p>
+<ul class="simple">
+<li>For <tt class="docutils literal"><span class="pre">__weak</span></tt> objects, the current pointee is retained and then released at
+the end of the current full-expression.  This must execute atomically with
+respect to assignments and to the final release of the pointee.</li>
+<li>For all other objects, the lvalue is loaded with primitive semantics.</li>
+</ul>
+<p><span class="arc-term">Assignment</span> occurs when evaluating an assignment operator.  The
+semantics vary based on the qualification:</p>
+<ul class="simple">
+<li>For <tt class="docutils literal"><span class="pre">__strong</span></tt> objects, the new pointee is first retained; second, the
+lvalue is loaded with primitive semantics; third, the new pointee is stored
+into the lvalue with primitive semantics; and finally, the old pointee is
+released.  This is not performed atomically; external synchronization must be
+used to make this safe in the face of concurrent loads and stores.</li>
+<li>For <tt class="docutils literal"><span class="pre">__weak</span></tt> objects, the lvalue is updated to point to the new pointee,
+unless the new pointee is an object currently undergoing deallocation, in
+which case the lvalue is updated to a null pointer.  This must execute
+atomically with respect to other assignments to the object, to reads from the
+object, and to the final release of the new pointee.</li>
+<li>For <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> objects, the new pointee is stored into the
+lvalue using primitive semantics.</li>
+<li>For <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> objects, the new pointee is retained, autoreleased,
+and stored into the lvalue using primitive semantics.</li>
+</ul>
+<p><span class="arc-term">Initialization</span> occurs when an object’s lifetime begins, which
+depends on its storage duration.  Initialization proceeds in two stages:</p>
+<ol class="arabic simple">
+<li>First, a null pointer is stored into the lvalue using primitive semantics.
+This step is skipped if the object is <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>.</li>
+<li>Second, if the object has an initializer, that expression is evaluated and
+then assigned into the object using the usual assignment semantics.</li>
+</ol>
+<p><span class="arc-term">Destruction</span> occurs when an object’s lifetime ends.  In all cases it
+is semantically equivalent to assigning a null pointer to the object, with the
+proviso that of course the object cannot be legally read after the object’s
+lifetime ends.</p>
+<p><span class="arc-term">Moving</span> occurs in specific situations where an lvalue is “moved
+from”, meaning that its current pointee will be used but the object may be left
+in a different (but still valid) state.  This arises with <tt class="docutils literal"><span class="pre">__block</span></tt> variables
+and rvalue references in C++.  For <tt class="docutils literal"><span class="pre">__strong</span></tt> lvalues, moving is equivalent
+to loading the lvalue with primitive semantics, writing a null pointer to it
+with primitive semantics, and then releasing the result of the load at the end
+of the current full-expression.  For all other lvalues, moving is equivalent to
+reading the object.</p>
+</div>
+<div class="section" id="arc-ownership-restrictions">
+<span id="id1"></span><h3><a class="toc-backref" href="#id24">Restrictions</a><a class="headerlink" href="#arc-ownership-restrictions" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="weak-unavailable-types">
+<span id="arc-ownership-restrictions-weak"></span><h4><a class="toc-backref" href="#id25">Weak-unavailable types</a><a class="headerlink" href="#weak-unavailable-types" title="Permalink to this headline">¶</a></h4>
+<p>It is explicitly permitted for Objective-C classes to not support <tt class="docutils literal"><span class="pre">__weak</span></tt>
+references.  It is undefined behavior to perform an operation with weak
+assignment semantics with a pointer to an Objective-C object whose class does
+not support <tt class="docutils literal"><span class="pre">__weak</span></tt> references.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Historically, it has been possible for a class to provide its own
+reference-count implementation by overriding <tt class="docutils literal"><span class="pre">retain</span></tt>, <tt class="docutils literal"><span class="pre">release</span></tt>, etc.
+However, weak references to an object require coordination with its class’s
+reference-count implementation because, among other things, weak loads and
+stores must be atomic with respect to the final release.  Therefore, existing
+custom reference-count implementations will generally not support weak
+references without additional effort.  This is unavoidable without breaking
+binary compatibility.</p>
+</div>
+<p>A class may indicate that it does not support weak references by providing the
+<tt class="docutils literal"><span class="pre">objc_arc_weak_reference_unavailable</span></tt> attribute on the class’s interface declaration.  A
+retainable object pointer type is <strong>weak-unavailable</strong> if
+is a pointer to an (optionally protocol-qualified) Objective-C class <tt class="docutils literal"><span class="pre">T</span></tt> where
+<tt class="docutils literal"><span class="pre">T</span></tt> or one of its superclasses has the <tt class="docutils literal"><span class="pre">objc_arc_weak_reference_unavailable</span></tt>
+attribute.  A program is ill-formed if it applies the <tt class="docutils literal"><span class="pre">__weak</span></tt> ownership
+qualifier to a weak-unavailable type or if the value operand of a weak
+assignment operation has a weak-unavailable type.</p>
+</div>
+<div class="section" id="storage-duration-of-autoreleasing-objects">
+<span id="arc-ownership-restrictions-autoreleasing"></span><h4><a class="toc-backref" href="#id26">Storage duration of <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> objects</a><a class="headerlink" href="#storage-duration-of-autoreleasing-objects" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it declares an <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> object of
+non-automatic storage duration.  A program is ill-formed if it captures an
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> object in a block or, unless by reference, in a C++11
+lambda.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Autorelease pools are tied to the current thread and scope by their nature.
+While it is possible to have temporary objects whose instance variables are
+filled with autoreleased objects, there is no way that ARC can provide any
+sort of safety guarantee there.</p>
+</div>
+<p>It is undefined behavior if a non-null pointer is assigned to an
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> object while an autorelease pool is in scope and then that
+object is read after the autorelease pool’s scope is left.</p>
+</div>
+<div class="section" id="conversion-of-pointers-to-ownership-qualified-types">
+<span id="arc-ownership-restrictions-conversion-indirect"></span><h4><a class="toc-backref" href="#id27">Conversion of pointers to ownership-qualified types</a><a class="headerlink" href="#conversion-of-pointers-to-ownership-qualified-types" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if an expression of type <tt class="docutils literal"><span class="pre">T*</span></tt> is converted,
+explicitly or implicitly, to the type <tt class="docutils literal"><span class="pre">U*</span></tt>, where <tt class="docutils literal"><span class="pre">T</span></tt> and <tt class="docutils literal"><span class="pre">U</span></tt> have
+different ownership qualification, unless:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">T</span></tt> is qualified with <tt class="docutils literal"><span class="pre">__strong</span></tt>, <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt>, or
+<tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>, and <tt class="docutils literal"><span class="pre">U</span></tt> is qualified with both <tt class="docutils literal"><span class="pre">const</span></tt> and
+<tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>; or</li>
+<li>either <tt class="docutils literal"><span class="pre">T</span></tt> or <tt class="docutils literal"><span class="pre">U</span></tt> is <tt class="docutils literal"><span class="pre">cv</span> <span class="pre">void</span></tt>, where <tt class="docutils literal"><span class="pre">cv</span></tt> is an optional sequence
+of non-ownership qualifiers; or</li>
+<li>the conversion is requested with a <tt class="docutils literal"><span class="pre">reinterpret_cast</span></tt> in Objective-C++; or</li>
+<li>the conversion is a well-formed <a class="reference internal" href="#arc-ownership-restrictions-pass-by-writeback"><em>pass-by-writeback</em></a>.</li>
+</ul>
+<p>The analogous rule applies to <tt class="docutils literal"><span class="pre">T&</span></tt> and <tt class="docutils literal"><span class="pre">U&</span></tt> in Objective-C++.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">These rules provide a reasonable level of type-safety for indirect pointers,
+as long as the underlying memory is not deallocated.  The conversion to
+<tt class="docutils literal"><span class="pre">const</span> <span class="pre">__unsafe_unretained</span></tt> is permitted because the semantics of reads are
+equivalent across all these ownership semantics, and that’s a very useful and
+common pattern.  The interconversion with <tt class="docutils literal"><span class="pre">void*</span></tt> is useful for allocating
+memory or otherwise escaping the type system, but use it carefully.
+<tt class="docutils literal"><span class="pre">reinterpret_cast</span></tt> is considered to be an obvious enough sign of taking
+responsibility for any problems.</p>
+</div>
+<p>It is undefined behavior to access an ownership-qualified object through an
+lvalue of a differently-qualified type, except that any non-<tt class="docutils literal"><span class="pre">__weak</span></tt> object
+may be read through an <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> lvalue.</p>
+<p>It is undefined behavior if a managed operation is performed on a <tt class="docutils literal"><span class="pre">__strong</span></tt>
+or <tt class="docutils literal"><span class="pre">__weak</span></tt> object without a guarantee that it contains a primitive zero
+bit-pattern, or if the storage for such an object is freed or reused without the
+object being first assigned a null pointer.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">ARC cannot differentiate between an assignment operator which is intended to
+“initialize” dynamic memory and one which is intended to potentially replace
+a value.  Therefore the object’s pointer must be valid before letting ARC at
+it.  Similarly, C and Objective-C do not provide any language hooks for
+destroying objects held in dynamic memory, so it is the programmer’s
+responsibility to avoid leaks (<tt class="docutils literal"><span class="pre">__strong</span></tt> objects) and consistency errors
+(<tt class="docutils literal"><span class="pre">__weak</span></tt> objects).</p>
+</div>
+<p>These requirements are followed automatically in Objective-C++ when creating
+objects of retainable object owner type with <tt class="docutils literal"><span class="pre">new</span></tt> or <tt class="docutils literal"><span class="pre">new[]</span></tt> and destroying
+them with <tt class="docutils literal"><span class="pre">delete</span></tt>, <tt class="docutils literal"><span class="pre">delete[]</span></tt>, or a pseudo-destructor expression.  Note
+that arrays of nontrivially-ownership-qualified type are not ABI compatible with
+non-ARC code because the element type is non-POD: such arrays that are
+<tt class="docutils literal"><span class="pre">new[]</span></tt>‘d in ARC translation units cannot be <tt class="docutils literal"><span class="pre">delete[]</span></tt>‘d in non-ARC
+translation units and vice-versa.</p>
+</div>
+<div class="section" id="passing-to-an-out-parameter-by-writeback">
+<span id="arc-ownership-restrictions-pass-by-writeback"></span><h4><a class="toc-backref" href="#id28">Passing to an out parameter by writeback</a><a class="headerlink" href="#passing-to-an-out-parameter-by-writeback" title="Permalink to this headline">¶</a></h4>
+<p>If the argument passed to a parameter of type <tt class="docutils literal"><span class="pre">T</span> <span class="pre">__autoreleasing</span> <span class="pre">*</span></tt> has type
+<tt class="docutils literal"><span class="pre">U</span> <span class="pre">oq</span> <span class="pre">*</span></tt>, where <tt class="docutils literal"><span class="pre">oq</span></tt> is an ownership qualifier, then the argument is a
+candidate for <span class="arc-term">pass-by-writeback`</span> if:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">oq</span></tt> is <tt class="docutils literal"><span class="pre">__strong</span></tt> or <tt class="docutils literal"><span class="pre">__weak</span></tt>, and</li>
+<li>it would be legal to initialize a <tt class="docutils literal"><span class="pre">T</span> <span class="pre">__strong</span> <span class="pre">*</span></tt> with a <tt class="docutils literal"><span class="pre">U</span> <span class="pre">__strong</span> <span class="pre">*</span></tt>.</li>
+</ul>
+<p>For purposes of overload resolution, an implicit conversion sequence requiring
+a pass-by-writeback is always worse than an implicit conversion sequence not
+requiring a pass-by-writeback.</p>
+<p>The pass-by-writeback is ill-formed if the argument expression does not have a
+legal form:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">&var</span></tt>, where <tt class="docutils literal"><span class="pre">var</span></tt> is a scalar variable of automatic storage duration
+with retainable object pointer type</li>
+<li>a conditional expression where the second and third operands are both legal
+forms</li>
+<li>a cast whose operand is a legal form</li>
+<li>a null pointer constant</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The restriction in the form of the argument serves two purposes.  First, it
+makes it impossible to pass the address of an array to the argument, which
+serves to protect against an otherwise serious risk of mis-inferring an
+“array” argument as an out-parameter.  Second, it makes it much less likely
+that the user will see confusing aliasing problems due to the implementation,
+below, where their store to the writeback temporary is not immediately seen
+in the original argument variable.</p>
+</div>
+<p>A pass-by-writeback is evaluated as follows:</p>
+<ol class="arabic simple">
+<li>The argument is evaluated to yield a pointer <tt class="docutils literal"><span class="pre">p</span></tt> of type <tt class="docutils literal"><span class="pre">U</span> <span class="pre">oq</span> <span class="pre">*</span></tt>.</li>
+<li>If <tt class="docutils literal"><span class="pre">p</span></tt> is a null pointer, then a null pointer is passed as the argument,
+and no further work is required for the pass-by-writeback.</li>
+<li>Otherwise, a temporary of type <tt class="docutils literal"><span class="pre">T</span> <span class="pre">__autoreleasing</span></tt> is created and
+initialized to a null pointer.</li>
+<li>If the parameter is not an Objective-C method parameter marked <tt class="docutils literal"><span class="pre">out</span></tt>,
+then <tt class="docutils literal"><span class="pre">*p</span></tt> is read, and the result is written into the temporary with
+primitive semantics.</li>
+<li>The address of the temporary is passed as the argument to the actual call.</li>
+<li>After the call completes, the temporary is loaded with primitive
+semantics, and that value is assigned into <tt class="docutils literal"><span class="pre">*p</span></tt>.</li>
+</ol>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This is all admittedly convoluted.  In an ideal world, we would see that a
+local variable is being passed to an out-parameter and retroactively modify
+its type to be <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> rather than <tt class="docutils literal"><span class="pre">__strong</span></tt>.  This would be
+remarkably difficult and not always well-founded under the C type system.
+However, it was judged unacceptably invasive to require programmers to write
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> on all the variables they intend to use for
+out-parameters.  This was the least bad solution.</p>
+</div>
+</div>
+<div class="section" id="ownership-qualified-fields-of-structs-and-unions">
+<span id="arc-ownership-restrictions-records"></span><h4><a class="toc-backref" href="#id29">Ownership-qualified fields of structs and unions</a><a class="headerlink" href="#ownership-qualified-fields-of-structs-and-unions" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it declares a member of a C struct or union to have
+a nontrivially ownership-qualified type.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The resulting type would be non-POD in the C++ sense, but C does not give us
+very good language tools for managing the lifetime of aggregates, so it is
+more convenient to simply forbid them.  It is still possible to manage this
+with a <tt class="docutils literal"><span class="pre">void*</span></tt> or an <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt> object.</p>
+</div>
+<p>This restriction does not apply in Objective-C++.  However, nontrivally
+ownership-qualified types are considered non-POD: in C++11 terms, they are not
+trivially default constructible, copy constructible, move constructible, copy
+assignable, move assignable, or destructible.  It is a violation of C++’s One
+Definition Rule to use a class outside of ARC that, under ARC, would have a
+nontrivially ownership-qualified member.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Unlike in C, we can express all the necessary ARC semantics for
+ownership-qualified subobjects as suboperations of the (default) special
+member functions for the class.  These functions then become non-trivial.
+This has the non-obvious result that the class will have a non-trivial copy
+constructor and non-trivial destructor; if this would not normally be true
+outside of ARC, objects of the type will be passed and returned in an
+ABI-incompatible manner.</p>
+</div>
+</div>
+</div>
+<div class="section" id="ownership-inference">
+<span id="arc-ownership-inference"></span><h3><a class="toc-backref" href="#id30">Ownership inference</a><a class="headerlink" href="#ownership-inference" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="objects">
+<span id="arc-ownership-inference-variables"></span><h4><a class="toc-backref" href="#id31">Objects</a><a class="headerlink" href="#objects" title="Permalink to this headline">¶</a></h4>
+<p>If an object is declared with retainable object owner type, but without an
+explicit ownership qualifier, its type is implicitly adjusted to have
+<tt class="docutils literal"><span class="pre">__strong</span></tt> qualification.</p>
+<p>As a special case, if the object’s base type is <tt class="docutils literal"><span class="pre">Class</span></tt> (possibly
+protocol-qualified), the type is adjusted to have <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>
+qualification instead.</p>
+</div>
+<div class="section" id="indirect-parameters">
+<span id="arc-ownership-inference-indirect-parameters"></span><h4><a class="toc-backref" href="#id32">Indirect parameters</a><a class="headerlink" href="#indirect-parameters" title="Permalink to this headline">¶</a></h4>
+<p>If a function or method parameter has type <tt class="docutils literal"><span class="pre">T*</span></tt>, where <tt class="docutils literal"><span class="pre">T</span></tt> is an
+ownership-unqualified retainable object pointer type, then:</p>
+<ul class="simple">
+<li>if <tt class="docutils literal"><span class="pre">T</span></tt> is <tt class="docutils literal"><span class="pre">const</span></tt>-qualified or <tt class="docutils literal"><span class="pre">Class</span></tt>, then it is implicitly
+qualified with <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>;</li>
+<li>otherwise, it is implicitly qualified with <tt class="docutils literal"><span class="pre">__autoreleasing</span></tt>.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last"><tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> exists mostly for this case, the Cocoa convention for
+out-parameters.  Since a pointer to <tt class="docutils literal"><span class="pre">const</span></tt> is obviously not an
+out-parameter, we instead use a type more useful for passing arrays.  If the
+user instead intends to pass in a <em>mutable</em> array, inferring
+<tt class="docutils literal"><span class="pre">__autoreleasing</span></tt> is the wrong thing to do; this directs some of the
+caution in the following rules about writeback.</p>
+</div>
+<p>Such a type written anywhere else would be ill-formed by the general rule
+requiring ownership qualifiers.</p>
+<p>This rule does not apply in Objective-C++ if a parameter’s type is dependent in
+a template pattern and is only <em>instantiated</em> to a type which would be a
+pointer to an unqualified retainable object pointer type.  Such code is still
+ill-formed.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The convention is very unlikely to be intentional in template code.</p>
+</div>
+</div>
+<div class="section" id="template-arguments">
+<span id="arc-ownership-inference-template-arguments"></span><h4><a class="toc-backref" href="#id33">Template arguments</a><a class="headerlink" href="#template-arguments" title="Permalink to this headline">¶</a></h4>
+<p>If a template argument for a template type parameter is an retainable object
+owner type that does not have an explicit ownership qualifier, it is adjusted
+to have <tt class="docutils literal"><span class="pre">__strong</span></tt> qualification.  This adjustment occurs regardless of
+whether the template argument was deduced or explicitly specified.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last"><tt class="docutils literal"><span class="pre">__strong</span></tt> is a useful default for containers (e.g., <tt class="docutils literal"><span class="pre">std::vector<id></span></tt>),
+which would otherwise require explicit qualification.  Moreover, unqualified
+retainable object pointer types are unlikely to be useful within templates,
+since they generally need to have a qualifier applied to the before being
+used.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="method-families">
+<span id="arc-method-families"></span><h2><a class="toc-backref" href="#id34">Method families</a><a class="headerlink" href="#method-families" title="Permalink to this headline">¶</a></h2>
+<p>An Objective-C method may fall into a <span class="arc-term">method family</span>, which is a
+conventional set of behaviors ascribed to it by the Cocoa conventions.</p>
+<p>A method is in a certain method family if:</p>
+<ul class="simple">
+<li>it has a <tt class="docutils literal"><span class="pre">objc_method_family</span></tt> attribute placing it in that family; or if
+not that,</li>
+<li>it does not have an <tt class="docutils literal"><span class="pre">objc_method_family</span></tt> attribute placing it in a
+different or no family, and</li>
+<li>its selector falls into the corresponding selector family, and</li>
+<li>its signature obeys the added restrictions of the method family.</li>
+</ul>
+<p>A selector is in a certain selector family if, ignoring any leading
+underscores, the first component of the selector either consists entirely of
+the name of the method family or it begins with that name followed by a
+character other than a lowercase letter.  For example, <tt class="docutils literal"><span class="pre">_perform:with:</span></tt> and
+<tt class="docutils literal"><span class="pre">performWith:</span></tt> would fall into the <tt class="docutils literal"><span class="pre">perform</span></tt> family (if we recognized one),
+but <tt class="docutils literal"><span class="pre">performing:with</span></tt> would not.</p>
+<p>The families and their added restrictions are:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">alloc</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">copy</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">mutableCopy</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">new</span></tt> methods must return a retainable object pointer type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">init</span></tt> methods must be instance methods and must return an Objective-C
+pointer type.  Additionally, a program is ill-formed if it declares or
+contains a call to an <tt class="docutils literal"><span class="pre">init</span></tt> method whose return type is neither <tt class="docutils literal"><span class="pre">id</span></tt> nor
+a pointer to a super-class or sub-class of the declaring class (if the method
+was declared on a class) or the static receiver type of the call (if it was
+declared on a protocol).</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>There are a fair number of existing methods with <tt class="docutils literal"><span class="pre">init</span></tt>-like selectors
+which nonetheless don’t follow the <tt class="docutils literal"><span class="pre">init</span></tt> conventions.  Typically these
+are either accidental naming collisions or helper methods called during
+initialization.  Because of the peculiar retain/release behavior of
+<tt class="docutils literal"><span class="pre">init</span></tt> methods, it’s very important not to treat these methods as
+<tt class="docutils literal"><span class="pre">init</span></tt> methods if they aren’t meant to be.  It was felt that implicitly
+defining these methods out of the family based on the exact relationship
+between the return type and the declaring class would be much too subtle
+and fragile.  Therefore we identify a small number of legitimate-seeming
+return types and call everything else an error.  This serves the secondary
+purpose of encouraging programmers not to accidentally give methods names
+in the <tt class="docutils literal"><span class="pre">init</span></tt> family.</p>
+<p class="last">Note that a method with an <tt class="docutils literal"><span class="pre">init</span></tt>-family selector which returns a
+non-Objective-C type (e.g. <tt class="docutils literal"><span class="pre">void</span></tt>) is perfectly well-formed; it simply
+isn’t in the <tt class="docutils literal"><span class="pre">init</span></tt> family.</p>
+</div>
+</li>
+</ul>
+<p>A program is ill-formed if a method’s declarations, implementations, and
+overrides do not all have the same method family.</p>
+<div class="section" id="explicit-method-family-control">
+<span id="arc-family-attribute"></span><h3><a class="toc-backref" href="#id35">Explicit method family control</a><a class="headerlink" href="#explicit-method-family-control" title="Permalink to this headline">¶</a></h3>
+<p>A method may be annotated with the <tt class="docutils literal"><span class="pre">objc_method_family</span></tt> attribute to
+precisely control which method family it belongs to.  If a method in an
+<tt class="docutils literal"><span class="pre">@implementation</span></tt> does not have this attribute, but there is a method
+declared in the corresponding <tt class="docutils literal"><span class="pre">@interface</span></tt> that does, then the attribute is
+copied to the declaration in the <tt class="docutils literal"><span class="pre">@implementation</span></tt>.  The attribute is
+available outside of ARC, and may be tested for with the preprocessor query
+<tt class="docutils literal"><span class="pre">__has_attribute(objc_method_family)</span></tt>.</p>
+<p>The attribute is spelled
+<tt class="docutils literal"><span class="pre">__attribute__((objc_method_family(</span></tt> <em>family</em> <tt class="docutils literal"><span class="pre">)))</span></tt>.  If <em>family</em> is
+<tt class="docutils literal"><span class="pre">none</span></tt>, the method has no family, even if it would otherwise be considered to
+have one based on its selector and type.  Otherwise, <em>family</em> must be one of
+<tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">init</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, or <tt class="docutils literal"><span class="pre">new</span></tt>, in which case the
+method is considered to belong to the corresponding family regardless of its
+selector.  It is an error if a method that is explicitly added to a family in
+this way does not meet the requirements of the family other than the selector
+naming convention.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The rules codified in this document describe the standard conventions of
+Objective-C.  However, as these conventions have not heretofore been enforced
+by an unforgiving mechanical system, they are only imperfectly kept,
+especially as they haven’t always even been precisely defined.  While it is
+possible to define low-level ownership semantics with attributes like
+<tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt>, this attribute allows the user to communicate
+semantic intent, which is of use both to ARC (which, e.g., treats calls to
+<tt class="docutils literal"><span class="pre">init</span></tt> specially) and the static analyzer.</p>
+</div>
+</div>
+<div class="section" id="semantics-of-method-families">
+<span id="arc-family-semantics"></span><h3><a class="toc-backref" href="#id36">Semantics of method families</a><a class="headerlink" href="#semantics-of-method-families" title="Permalink to this headline">¶</a></h3>
+<p>A method’s membership in a method family may imply non-standard semantics for
+its parameters and return type.</p>
+<p>Methods in the <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, and <tt class="docutils literal"><span class="pre">new</span></tt> families —
+that is, methods in all the currently-defined families except <tt class="docutils literal"><span class="pre">init</span></tt> —
+implicitly <a class="reference internal" href="#arc-object-operands-retained-return-values"><em>return a retained object</em></a> as if they were annotated with
+the <tt class="docutils literal"><span class="pre">ns_returns_retained</span></tt> attribute.  This can be overridden by annotating
+the method with either of the <tt class="docutils literal"><span class="pre">ns_returns_autoreleased</span></tt> or
+<tt class="docutils literal"><span class="pre">ns_returns_not_retained</span></tt> attributes.</p>
+<p>Properties also follow same naming rules as methods.  This means that those in
+the <tt class="docutils literal"><span class="pre">alloc</span></tt>, <tt class="docutils literal"><span class="pre">copy</span></tt>, <tt class="docutils literal"><span class="pre">mutableCopy</span></tt>, and <tt class="docutils literal"><span class="pre">new</span></tt> families provide access
+to <a class="reference internal" href="#arc-object-operands-retained-return-values"><em>retained objects</em></a>.  This
+can be overridden by annotating the property with <tt class="docutils literal"><span class="pre">ns_returns_not_retained</span></tt>
+attribute.</p>
+<div class="section" id="semantics-of-init">
+<span id="arc-family-semantics-init"></span><h4><a class="toc-backref" href="#id37">Semantics of <tt class="docutils literal"><span class="pre">init</span></tt></a><a class="headerlink" href="#semantics-of-init" title="Permalink to this headline">¶</a></h4>
+<p>Methods in the <tt class="docutils literal"><span class="pre">init</span></tt> family implicitly <a class="reference internal" href="#arc-objects-operands-consumed"><em>consume</em></a> their <tt class="docutils literal"><span class="pre">self</span></tt> parameter and <a class="reference internal" href="#arc-object-operands-retained-return-values"><em>return a
+retained object</em></a>.  Neither of
+these properties can be altered through attributes.</p>
+<p>A call to an <tt class="docutils literal"><span class="pre">init</span></tt> method with a receiver that is either <tt class="docutils literal"><span class="pre">self</span></tt> (possibly
+parenthesized or casted) or <tt class="docutils literal"><span class="pre">super</span></tt> is called a <span class="arc-term">delegate init
+call</span>.  It is an error for a delegate init call to be made except from an
+<tt class="docutils literal"><span class="pre">init</span></tt> method, and excluding blocks within such methods.</p>
+<p>As an exception to the <a class="reference internal" href="#arc-misc-self"><em>usual rule</em></a>, the variable <tt class="docutils literal"><span class="pre">self</span></tt>
+is mutable in an <tt class="docutils literal"><span class="pre">init</span></tt> method and has the usual semantics for a <tt class="docutils literal"><span class="pre">__strong</span></tt>
+variable.  However, it is undefined behavior and the program is ill-formed, no
+diagnostic required, if an <tt class="docutils literal"><span class="pre">init</span></tt> method attempts to use the previous value
+of <tt class="docutils literal"><span class="pre">self</span></tt> after the completion of a delegate init call.  It is conventional,
+but not required, for an <tt class="docutils literal"><span class="pre">init</span></tt> method to return <tt class="docutils literal"><span class="pre">self</span></tt>.</p>
+<p>It is undefined behavior for a program to cause two or more calls to <tt class="docutils literal"><span class="pre">init</span></tt>
+methods on the same object, except that each <tt class="docutils literal"><span class="pre">init</span></tt> method invocation may
+perform at most one delegate init call.</p>
+</div>
+<div class="section" id="related-result-types">
+<span id="arc-family-semantics-result-type"></span><h4><a class="toc-backref" href="#id38">Related result types</a><a class="headerlink" href="#related-result-types" title="Permalink to this headline">¶</a></h4>
+<p>Certain methods are candidates to have <span class="arc-term">related result types</span>:</p>
+<ul class="simple">
+<li>class methods in the <tt class="docutils literal"><span class="pre">alloc</span></tt> and <tt class="docutils literal"><span class="pre">new</span></tt> method families</li>
+<li>instance methods in the <tt class="docutils literal"><span class="pre">init</span></tt> family</li>
+<li>the instance method <tt class="docutils literal"><span class="pre">self</span></tt></li>
+<li>outside of ARC, the instance methods <tt class="docutils literal"><span class="pre">retain</span></tt> and <tt class="docutils literal"><span class="pre">autorelease</span></tt></li>
+</ul>
+<p>If the formal result type of such a method is <tt class="docutils literal"><span class="pre">id</span></tt> or protocol-qualified
+<tt class="docutils literal"><span class="pre">id</span></tt>, or a type equal to the declaring class or a superclass, then it is said
+to have a related result type.  In this case, when invoked in an explicit
+message send, it is assumed to return a type related to the type of the
+receiver:</p>
+<ul class="simple">
+<li>if it is a class method, and the receiver is a class name <tt class="docutils literal"><span class="pre">T</span></tt>, the message
+send expression has type <tt class="docutils literal"><span class="pre">T*</span></tt>; otherwise</li>
+<li>if it is an instance method, and the receiver has type <tt class="docutils literal"><span class="pre">T</span></tt>, the message
+send expression has type <tt class="docutils literal"><span class="pre">T</span></tt>; otherwise</li>
+<li>the message send expression has the normal result type of the method.</li>
+</ul>
+<p>This is a new rule of the Objective-C language and applies outside of ARC.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">ARC’s automatic code emission is more prone than most code to signature
+errors, i.e. errors where a call was emitted against one method signature,
+but the implementing method has an incompatible signature.  Having more
+precise type information helps drastically lower this risk, as well as
+catching a number of latent bugs.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="optimization">
+<span id="arc-optimization"></span><h2><a class="toc-backref" href="#id39">Optimization</a><a class="headerlink" href="#optimization" title="Permalink to this headline">¶</a></h2>
+<p>Within this section, the word <span class="arc-term">function</span> will be used to
+refer to any structured unit of code, be it a C function, an
+Objective-C method, or a block.</p>
+<p>This specification describes ARC as performing specific <tt class="docutils literal"><span class="pre">retain</span></tt> and
+<tt class="docutils literal"><span class="pre">release</span></tt> operations on retainable object pointers at specific
+points during the execution of a program.  These operations make up a
+non-contiguous subsequence of the computation history of the program.
+The portion of this sequence for a particular retainable object
+pointer for which a specific function execution is directly
+responsible is the <span class="arc-term">formal local retain history</span> of the
+object pointer.  The corresponding actual sequence executed is the
+<cite>dynamic local retain history</cite>.</p>
+<p>However, under certain circumstances, ARC is permitted to re-order and
+eliminate operations in a manner which may alter the overall
+computation history beyond what is permitted by the general “as if”
+rule of C/C++ and the <a class="reference internal" href="#arc-objects-retains"><em>restrictions</em></a> on
+the implementation of <tt class="docutils literal"><span class="pre">retain</span></tt> and <tt class="docutils literal"><span class="pre">release</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Specifically, ARC is sometimes permitted to optimize <tt class="docutils literal"><span class="pre">release</span></tt>
+operations in ways which might cause an object to be deallocated
+before it would otherwise be.  Without this, it would be almost
+impossible to eliminate any <tt class="docutils literal"><span class="pre">retain</span></tt>/<tt class="docutils literal"><span class="pre">release</span></tt> pairs.  For
+example, consider the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="n">x</span> <span class="o">=</span> <span class="n">_ivar</span><span class="p">;</span>
+<span class="p">[</span><span class="n">x</span> <span class="n">foo</span><span class="p">];</span>
+</pre></div>
+</div>
+<p class="last">If we were not permitted in any event to shorten the lifetime of the
+object in <tt class="docutils literal"><span class="pre">x</span></tt>, then we would not be able to eliminate this retain
+and release unless we could prove that the message send could not
+modify <tt class="docutils literal"><span class="pre">_ivar</span></tt> (or deallocate <tt class="docutils literal"><span class="pre">self</span></tt>).  Since message sends are
+opaque to the optimizer, this is not possible, and so ARC’s hands
+would be almost completely tied.</p>
+</div>
+<p>ARC makes no guarantees about the execution of a computation history
+which contains undefined behavior.  In particular, ARC makes no
+guarantees in the presence of race conditions.</p>
+<p>ARC may assume that any retainable object pointers it receives or
+generates are instantaneously valid from that point until a point
+which, by the concurrency model of the host language, happens-after
+the generation of the pointer and happens-before a release of that
+object (possibly via an aliasing pointer or indirectly due to
+destruction of a different object).</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">There is very little point in trying to guarantee correctness in the
+presence of race conditions.  ARC does not have a stack-scanning
+garbage collector, and guaranteeing the atomicity of every load and
+store operation would be prohibitive and preclude a vast amount of
+optimization.</p>
+</div>
+<p>ARC may assume that non-ARC code engages in sensible balancing
+behavior and does not rely on exact or minimum retain count values
+except as guaranteed by <tt class="docutils literal"><span class="pre">__strong</span></tt> object invariants or +1 transfer
+conventions.  For example, if an object is provably double-retained
+and double-released, ARC may eliminate the inner retain and release;
+it does not need to guard against code which performs an unbalanced
+release followed by a “balancing” retain.</p>
+<div class="section" id="object-liveness">
+<span id="arc-optimization-liveness"></span><h3><a class="toc-backref" href="#id40">Object liveness</a><a class="headerlink" href="#object-liveness" title="Permalink to this headline">¶</a></h3>
+<p>ARC may not allow a retainable object <tt class="docutils literal"><span class="pre">X</span></tt> to be deallocated at a
+time <tt class="docutils literal"><span class="pre">T</span></tt> in a computation history if:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">X</span></tt> is the value stored in a <tt class="docutils literal"><span class="pre">__strong</span></tt> object <tt class="docutils literal"><span class="pre">S</span></tt> with
+<a class="reference internal" href="#arc-optimization-precise"><em>precise lifetime semantics</em></a>, or</li>
+<li><tt class="docutils literal"><span class="pre">X</span></tt> is the value stored in a <tt class="docutils literal"><span class="pre">__strong</span></tt> object <tt class="docutils literal"><span class="pre">S</span></tt> with
+imprecise lifetime semantics and, at some point after <tt class="docutils literal"><span class="pre">T</span></tt> but
+before the next store to <tt class="docutils literal"><span class="pre">S</span></tt>, the computation history features a
+load from <tt class="docutils literal"><span class="pre">S</span></tt> and in some way depends on the value loaded, or</li>
+<li><tt class="docutils literal"><span class="pre">X</span></tt> is a value described as being released at the end of the
+current full-expression and, at some point after <tt class="docutils literal"><span class="pre">T</span></tt> but before
+the end of the full-expression, the computation history depends
+on that value.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The intent of the second rule is to say that objects held in normal
+<tt class="docutils literal"><span class="pre">__strong</span></tt> local variables may be released as soon as the value in
+the variable is no longer being used: either the variable stops
+being used completely or a new value is stored in the variable.</p>
+<p class="last">The intent of the third rule is to say that return values may be
+released after they’ve been used.</p>
+</div>
+<p>A computation history depends on a pointer value <tt class="docutils literal"><span class="pre">P</span></tt> if it:</p>
+<ul class="simple">
+<li>performs a pointer comparison with <tt class="docutils literal"><span class="pre">P</span></tt>,</li>
+<li>loads from <tt class="docutils literal"><span class="pre">P</span></tt>,</li>
+<li>stores to <tt class="docutils literal"><span class="pre">P</span></tt>,</li>
+<li>depends on a pointer value <tt class="docutils literal"><span class="pre">Q</span></tt> derived via pointer arithmetic
+from <tt class="docutils literal"><span class="pre">P</span></tt> (including an instance-variable or field access), or</li>
+<li>depends on a pointer value <tt class="docutils literal"><span class="pre">Q</span></tt> loaded from <tt class="docutils literal"><span class="pre">P</span></tt>.</li>
+</ul>
+<p>Dependency applies only to values derived directly or indirectly from
+a particular expression result and does not occur merely because a
+separate pointer value dynamically aliases <tt class="docutils literal"><span class="pre">P</span></tt>.  Furthermore, this
+dependency is not carried by values that are stored to objects.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The restrictions on dependency are intended to make this analysis
+feasible by an optimizer with only incomplete information about a
+program.  Essentially, dependence is carried to “obvious” uses of a
+pointer.  Merely passing a pointer argument to a function does not
+itself cause dependence, but since generally the optimizer will not
+be able to prove that the function doesn’t depend on that parameter,
+it will be forced to conservatively assume it does.</p>
+<p>Dependency propagates to values loaded from a pointer because those
+values might be invalidated by deallocating the object.  For
+example, given the code <tt class="docutils literal"><span class="pre">__strong</span> <span class="pre">id</span> <span class="pre">x</span> <span class="pre">=</span> <span class="pre">p->ivar;</span></tt>, ARC must not
+move the release of <tt class="docutils literal"><span class="pre">p</span></tt> to between the load of <tt class="docutils literal"><span class="pre">p->ivar</span></tt> and the
+retain of that value for storing into <tt class="docutils literal"><span class="pre">x</span></tt>.</p>
+<p>Dependency does not propagate through stores of dependent pointer
+values because doing so would allow dependency to outlive the
+full-expression which produced the original value.  For example, the
+address of an instance variable could be written to some global
+location and then freely accessed during the lifetime of the local,
+or a function could return an inner pointer of an object and store
+it to a local.  These cases would be potentially impossible to
+reason about and so would basically prevent any optimizations based
+on imprecise lifetime.  There are also uncommon enough to make it
+reasonable to require the precise-lifetime annotation if someone
+really wants to rely on them.</p>
+<p class="last">Dependency does propagate through return values of pointer type.
+The compelling source of need for this rule is a property accessor
+which returns an un-autoreleased result; the calling function must
+have the chance to operate on the value, e.g. to retain it, before
+ARC releases the original pointer.  Note again, however, that
+dependence does not survive a store, so ARC does not guarantee the
+continued validity of the return value past the end of the
+full-expression.</p>
+</div>
+</div>
+<div class="section" id="no-object-lifetime-extension">
+<span id="arc-optimization-object-lifetime"></span><h3><a class="toc-backref" href="#id41">No object lifetime extension</a><a class="headerlink" href="#no-object-lifetime-extension" title="Permalink to this headline">¶</a></h3>
+<p>If, in the formal computation history of the program, an object <tt class="docutils literal"><span class="pre">X</span></tt>
+has been deallocated by the time of an observable side-effect, then
+ARC must cause <tt class="docutils literal"><span class="pre">X</span></tt> to be deallocated by no later than the occurrence
+of that side-effect, except as influenced by the re-ordering of the
+destruction of objects.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>This rule is intended to prohibit ARC from observably extending the
+lifetime of a retainable object, other than as specified in this
+document.  Together with the rule limiting the transformation of
+releases, this rule requires ARC to eliminate retains and release
+only in pairs.</p>
+<p class="last">ARC’s power to reorder the destruction of objects is critical to its
+ability to do any optimization, for essentially the same reason that
+it must retain the power to decrease the lifetime of an object.
+Unfortunately, while it’s generally poor style for the destruction
+of objects to have arbitrary side-effects, it’s certainly possible.
+Hence the caveat.</p>
+</div>
+</div>
+<div class="section" id="precise-lifetime-semantics">
+<span id="arc-optimization-precise"></span><h3><a class="toc-backref" href="#id42">Precise lifetime semantics</a><a class="headerlink" href="#precise-lifetime-semantics" title="Permalink to this headline">¶</a></h3>
+<p>In general, ARC maintains an invariant that a retainable object pointer held in
+a <tt class="docutils literal"><span class="pre">__strong</span></tt> object will be retained for the full formal lifetime of the
+object.  Objects subject to this invariant have <span class="arc-term">precise lifetime
+semantics</span>.</p>
+<p>By default, local variables of automatic storage duration do not have precise
+lifetime semantics.  Such objects are simply strong references which hold
+values of retainable object pointer type, and these values are still fully
+subject to the optimizations on values under local control.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Applying these precise-lifetime semantics strictly would be prohibitive.
+Many useful optimizations that might theoretically decrease the lifetime of
+an object would be rendered impossible.  Essentially, it promises too much.</p>
+</div>
+<p>A local variable of retainable object owner type and automatic storage duration
+may be annotated with the <tt class="docutils literal"><span class="pre">objc_precise_lifetime</span></tt> attribute to indicate that
+it should be considered to be an object with precise lifetime semantics.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Nonetheless, it is sometimes useful to be able to force an object to be
+released at a precise time, even if that object does not appear to be used.
+This is likely to be uncommon enough that the syntactic weight of explicitly
+requesting these semantics will not be burdensome, and may even make the code
+clearer.</p>
+</div>
+</div>
+</div>
+<div class="section" id="miscellaneous">
+<span id="arc-misc"></span><h2><a class="toc-backref" href="#id43">Miscellaneous</a><a class="headerlink" href="#miscellaneous" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="special-methods">
+<span id="arc-misc-special-methods"></span><h3><a class="toc-backref" href="#id44">Special methods</a><a class="headerlink" href="#special-methods" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="memory-management-methods">
+<span id="arc-misc-special-methods-retain"></span><h4><a class="toc-backref" href="#id45">Memory management methods</a><a class="headerlink" href="#memory-management-methods" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it contains a method definition, message send, or
+<tt class="docutils literal"><span class="pre">@selector</span></tt> expression for any of the following selectors:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">autorelease</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">release</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">retain</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">retainCount</span></tt></li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p><tt class="docutils literal"><span class="pre">retainCount</span></tt> is banned because ARC robs it of consistent semantics.  The
+others were banned after weighing three options for how to deal with message
+sends:</p>
+<p><strong>Honoring</strong> them would work out very poorly if a programmer naively or
+accidentally tried to incorporate code written for manual retain/release code
+into an ARC program.  At best, such code would do twice as much work as
+necessary; quite frequently, however, ARC and the explicit code would both
+try to balance the same retain, leading to crashes.  The cost is losing the
+ability to perform “unrooted” retains, i.e. retains not logically
+corresponding to a strong reference in the object graph.</p>
+<p><strong>Ignoring</strong> them would badly violate user expectations about their code.
+While it <em>would</em> make it easier to develop code simultaneously for ARC and
+non-ARC, there is very little reason to do so except for certain library
+developers.  ARC and non-ARC translation units share an execution model and
+can seamlessly interoperate.  Within a translation unit, a developer who
+faithfully maintains their code in non-ARC mode is suffering all the
+restrictions of ARC for zero benefit, while a developer who isn’t testing the
+non-ARC mode is likely to be unpleasantly surprised if they try to go back to
+it.</p>
+<p><strong>Banning</strong> them has the disadvantage of making it very awkward to migrate
+existing code to ARC.  The best answer to that, given a number of other
+changes and restrictions in ARC, is to provide a specialized tool to assist
+users in that migration.</p>
+<p class="last">Implementing these methods was banned because they are too integral to the
+semantics of ARC; many tricks which worked tolerably under manual reference
+counting will misbehave if ARC performs an ephemeral extra retain or two.  If
+absolutely required, it is still possible to implement them in non-ARC code,
+for example in a category; the implementations must obey the <a class="reference internal" href="#arc-objects-retains"><em>semantics</em></a> laid out elsewhere in this document.</p>
+</div>
+</div>
+<div class="section" id="dealloc">
+<span id="arc-misc-special-methods-dealloc"></span><h4><a class="toc-backref" href="#id46"><tt class="docutils literal"><span class="pre">dealloc</span></tt></a><a class="headerlink" href="#dealloc" title="Permalink to this headline">¶</a></h4>
+<p>A program is ill-formed if it contains a message send or <tt class="docutils literal"><span class="pre">@selector</span></tt>
+expression for the selector <tt class="docutils literal"><span class="pre">dealloc</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">There are no legitimate reasons to call <tt class="docutils literal"><span class="pre">dealloc</span></tt> directly.</p>
+</div>
+<p>A class may provide a method definition for an instance method named
+<tt class="docutils literal"><span class="pre">dealloc</span></tt>.  This method will be called after the final <tt class="docutils literal"><span class="pre">release</span></tt> of the
+object but before it is deallocated or any of its instance variables are
+destroyed.  The superclass’s implementation of <tt class="docutils literal"><span class="pre">dealloc</span></tt> will be called
+automatically when the method returns.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Even though ARC destroys instance variables automatically, there are still
+legitimate reasons to write a <tt class="docutils literal"><span class="pre">dealloc</span></tt> method, such as freeing
+non-retainable resources.  Failing to call <tt class="docutils literal"><span class="pre">[super</span> <span class="pre">dealloc]</span></tt> in such a
+method is nearly always a bug.  Sometimes, the object is simply trying to
+prevent itself from being destroyed, but <tt class="docutils literal"><span class="pre">dealloc</span></tt> is really far too late
+for the object to be raising such objections.  Somewhat more legitimately, an
+object may have been pool-allocated and should not be deallocated with
+<tt class="docutils literal"><span class="pre">free</span></tt>; for now, this can only be supported with a <tt class="docutils literal"><span class="pre">dealloc</span></tt>
+implementation outside of ARC.  Such an implementation must be very careful
+to do all the other work that <tt class="docutils literal"><span class="pre">NSObject</span></tt>‘s <tt class="docutils literal"><span class="pre">dealloc</span></tt> would, which is
+outside the scope of this document to describe.</p>
+</div>
+<p>The instance variables for an ARC-compiled class will be destroyed at some
+point after control enters the <tt class="docutils literal"><span class="pre">dealloc</span></tt> method for the root class of the
+class.  The ordering of the destruction of instance variables is unspecified,
+both within a single class and between subclasses and superclasses.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>The traditional, non-ARC pattern for destroying instance variables is to
+destroy them immediately before calling <tt class="docutils literal"><span class="pre">[super</span> <span class="pre">dealloc]</span></tt>.  Unfortunately,
+message sends from the superclass are quite capable of reaching methods in
+the subclass, and those methods may well read or write to those instance
+variables.  Making such message sends from dealloc is generally discouraged,
+since the subclass may well rely on other invariants that were broken during
+<tt class="docutils literal"><span class="pre">dealloc</span></tt>, but it’s not so inescapably dangerous that we felt comfortable
+calling it undefined behavior.  Therefore we chose to delay destroying the
+instance variables to a point at which message sends are clearly disallowed:
+the point at which the root class’s deallocation routines take over.</p>
+<p class="last">In most code, the difference is not observable.  It can, however, be observed
+if an instance variable holds a strong reference to an object whose
+deallocation will trigger a side-effect which must be carefully ordered with
+respect to the destruction of the super class.  Such code violates the design
+principle that semantically important behavior should be explicit.  A simple
+fix is to clear the instance variable manually during <tt class="docutils literal"><span class="pre">dealloc</span></tt>; a more
+holistic solution is to move semantically important side-effects out of
+<tt class="docutils literal"><span class="pre">dealloc</span></tt> and into a separate teardown phase which can rely on working with
+well-formed objects.</p>
+</div>
+</div>
+</div>
+<div class="section" id="autoreleasepool">
+<span id="arc-misc-autoreleasepool"></span><h3><a class="toc-backref" href="#id47"><tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt></a><a class="headerlink" href="#autoreleasepool" title="Permalink to this headline">¶</a></h3>
+<p>To simplify the use of autorelease pools, and to bring them under the control
+of the compiler, a new kind of statement is available in Objective-C.  It is
+written <tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt> followed by a <em>compound-statement</em>, i.e.  by a new
+scope delimited by curly braces.  Upon entry to this block, the current state
+of the autorelease pool is captured.  When the block is exited normally,
+whether by fallthrough or directed control flow (such as <tt class="docutils literal"><span class="pre">return</span></tt> or
+<tt class="docutils literal"><span class="pre">break</span></tt>), the autorelease pool is restored to the saved state, releasing all
+the objects in it.  When the block is exited with an exception, the pool is not
+drained.</p>
+<p><tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt> may be used in non-ARC translation units, with equivalent
+semantics.</p>
+<p>A program is ill-formed if it refers to the <tt class="docutils literal"><span class="pre">NSAutoreleasePool</span></tt> class.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Autorelease pools are clearly important for the compiler to reason about, but
+it is far too much to expect the compiler to accurately reason about control
+dependencies between two calls.  It is also very easy to accidentally forget
+to drain an autorelease pool when using the manual API, and this can
+significantly inflate the process’s high-water-mark.  The introduction of a
+new scope is unfortunate but basically required for sane interaction with the
+rest of the language.  Not draining the pool during an unwind is apparently
+required by the Objective-C exceptions implementation.</p>
+</div>
+</div>
+<div class="section" id="self">
+<span id="arc-misc-self"></span><h3><a class="toc-backref" href="#id48"><tt class="docutils literal"><span class="pre">self</span></tt></a><a class="headerlink" href="#self" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">self</span></tt> parameter variable of an Objective-C method is never actually
+retained by the implementation.  It is undefined behavior, or at least
+dangerous, to cause an object to be deallocated during a message send to that
+object.</p>
+<p>To make this safe, for Objective-C instance methods <tt class="docutils literal"><span class="pre">self</span></tt> is implicitly
+<tt class="docutils literal"><span class="pre">const</span></tt> unless the method is in the <a class="reference internal" href="#arc-family-semantics-init"><em>init family</em></a>.  Further, <tt class="docutils literal"><span class="pre">self</span></tt> is <strong>always</strong> implicitly
+<tt class="docutils literal"><span class="pre">const</span></tt> within a class method.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The cost of retaining <tt class="docutils literal"><span class="pre">self</span></tt> in all methods was found to be prohibitive, as
+it tends to be live across calls, preventing the optimizer from proving that
+the retain and release are unnecessary — for good reason, as it’s quite
+possible in theory to cause an object to be deallocated during its execution
+without this retain and release.  Since it’s extremely uncommon to actually
+do so, even unintentionally, and since there’s no natural way for the
+programmer to remove this retain/release pair otherwise (as there is for
+other parameters by, say, making the variable <tt class="docutils literal"><span class="pre">__unsafe_unretained</span></tt>), we
+chose to make this optimizing assumption and shift some amount of risk to the
+user.</p>
+</div>
+</div>
+<div class="section" id="fast-enumeration-iteration-variables">
+<span id="arc-misc-enumeration"></span><h3><a class="toc-backref" href="#id49">Fast enumeration iteration variables</a><a class="headerlink" href="#fast-enumeration-iteration-variables" title="Permalink to this headline">¶</a></h3>
+<p>If a variable is declared in the condition of an Objective-C fast enumeration
+loop, and the variable has no explicit ownership qualifier, then it is
+qualified with <tt class="docutils literal"><span class="pre">const</span> <span class="pre">__strong</span></tt> and objects encountered during the
+enumeration are not actually retained.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">This is an optimization made possible because fast enumeration loops promise
+to keep the objects retained during enumeration, and the collection itself
+cannot be synchronously modified.  It can be overridden by explicitly
+qualifying the variable with <tt class="docutils literal"><span class="pre">__strong</span></tt>, which will make the variable
+mutable again and cause the loop to retain the objects it encounters.</p>
+</div>
+</div>
+<div class="section" id="blocks">
+<span id="arc-misc-blocks"></span><h3><a class="toc-backref" href="#id50">Blocks</a><a class="headerlink" href="#blocks" title="Permalink to this headline">¶</a></h3>
+<p>The implicit <tt class="docutils literal"><span class="pre">const</span></tt> capture variables created when evaluating a block
+literal expression have the same ownership semantics as the local variables
+they capture.  The capture is performed by reading from the captured variable
+and initializing the capture variable with that value; the capture variable is
+destroyed when the block literal is, i.e. at the end of the enclosing scope.</p>
+<p>The <a class="reference internal" href="#arc-ownership-inference"><em>inference</em></a> rules apply equally to
+<tt class="docutils literal"><span class="pre">__block</span></tt> variables, which is a shift in semantics from non-ARC, where
+<tt class="docutils literal"><span class="pre">__block</span></tt> variables did not implicitly retain during capture.</p>
+<p><tt class="docutils literal"><span class="pre">__block</span></tt> variables of retainable object owner type are moved off the stack
+by initializing the heap copy with the result of moving from the stack copy.</p>
+<p>With the exception of retains done as part of initializing a <tt class="docutils literal"><span class="pre">__strong</span></tt>
+parameter variable or reading a <tt class="docutils literal"><span class="pre">__weak</span></tt> variable, whenever these semantics
+call for retaining a value of block-pointer type, it has the effect of a
+<tt class="docutils literal"><span class="pre">Block_copy</span></tt>.  The optimizer may remove such copies when it sees that the
+result is used only as an argument to a call.</p>
+</div>
+<div class="section" id="exceptions">
+<span id="arc-misc-exceptions"></span><h3><a class="toc-backref" href="#id51">Exceptions</a><a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3>
+<p>By default in Objective C, ARC is not exception-safe for normal releases:</p>
+<ul class="simple">
+<li>It does not end the lifetime of <tt class="docutils literal"><span class="pre">__strong</span></tt> variables when their scopes are
+abnormally terminated by an exception.</li>
+<li>It does not perform releases which would occur at the end of a
+full-expression if that full-expression throws an exception.</li>
+</ul>
+<p>A program may be compiled with the option <tt class="docutils literal"><span class="pre">-fobjc-arc-exceptions</span></tt> in order to
+enable these, or with the option <tt class="docutils literal"><span class="pre">-fno-objc-arc-exceptions</span></tt> to explicitly
+disable them, with the last such argument “winning”.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The standard Cocoa convention is that exceptions signal programmer error and
+are not intended to be recovered from.  Making code exceptions-safe by
+default would impose severe runtime and code size penalties on code that
+typically does not actually care about exceptions safety.  Therefore,
+ARC-generated code leaks by default on exceptions, which is just fine if the
+process is going to be immediately terminated anyway.  Programs which do care
+about recovering from exceptions should enable the option.</p>
+</div>
+<p>In Objective-C++, <tt class="docutils literal"><span class="pre">-fobjc-arc-exceptions</span></tt> is enabled by default.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">C++ already introduces pervasive exceptions-cleanup code of the sort that ARC
+introduces.  C++ programmers who have not already disabled exceptions are
+much more likely to actual require exception-safety.</p>
+</div>
+<p>ARC does end the lifetimes of <tt class="docutils literal"><span class="pre">__weak</span></tt> objects when an exception terminates
+their scope unless exceptions are disabled in the compiler.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">The consequence of a local <tt class="docutils literal"><span class="pre">__weak</span></tt> object not being destroyed is very
+likely to be corruption of the Objective-C runtime, so we want to be safer
+here.  Of course, potentially massive leaks are about as likely to take down
+the process as this corruption is if the program does try to recover from
+exceptions.</p>
+</div>
+</div>
+<div class="section" id="interior-pointers">
+<span id="arc-misc-interior"></span><h3><a class="toc-backref" href="#id52">Interior pointers</a><a class="headerlink" href="#interior-pointers" title="Permalink to this headline">¶</a></h3>
+<p>An Objective-C method returning a non-retainable pointer may be annotated with
+the <tt class="docutils literal"><span class="pre">objc_returns_inner_pointer</span></tt> attribute to indicate that it returns a
+handle to the internal data of an object, and that this reference will be
+invalidated if the object is destroyed.  When such a message is sent to an
+object, the object’s lifetime will be extended until at least the earliest of:</p>
+<ul class="simple">
+<li>the last use of the returned pointer, or any pointer derived from it, in the
+calling function or</li>
+<li>the autorelease pool is restored to a previous state.</li>
+</ul>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Rationale: not all memory and resources are managed with reference counts; it
+is common for objects to manage private resources in their own, private way.
+Typically these resources are completely encapsulated within the object, but
+some classes offer their users direct access for efficiency.  If ARC is not
+aware of methods that return such “interior” pointers, its optimizations can
+cause the owning object to be reclaimed too soon.  This attribute informs ARC
+that it must tread lightly.</p>
+<p class="last">The extension rules are somewhat intentionally vague.  The autorelease pool
+limit is there to permit a simple implementation to simply retain and
+autorelease the receiver.  The other limit permits some amount of
+optimization.  The phrase “derived from” is intended to encompass the results
+both of pointer transformations, such as casts and arithmetic, and of loading
+from such derived pointers; furthermore, it applies whether or not such
+derivations are applied directly in the calling code or by other utility code
+(for example, the C library routine <tt class="docutils literal"><span class="pre">strchr</span></tt>).  However, the implementation
+never need account for uses after a return from the code which calls the
+method returning an interior pointer.</p>
+</div>
+<p>As an exception, no extension is required if the receiver is loaded directly
+from a <tt class="docutils literal"><span class="pre">__strong</span></tt> object with <a class="reference internal" href="#arc-optimization-precise"><em>precise lifetime semantics</em></a>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Implicit autoreleases carry the risk of significantly inflating memory use,
+so it’s important to provide users a way of avoiding these autoreleases.
+Tying this to precise lifetime semantics is ideal, as for local variables
+this requires a very explicit annotation, which allows ARC to trust the user
+with good cheer.</p>
+</div>
+</div>
+<div class="section" id="c-retainable-pointer-types">
+<span id="arc-misc-c-retainable"></span><h3><a class="toc-backref" href="#id53">C retainable pointer types</a><a class="headerlink" href="#c-retainable-pointer-types" title="Permalink to this headline">¶</a></h3>
+<p>A type is a <span class="arc-term">C retainable pointer type</span> if it is a pointer to
+(possibly qualified) <tt class="docutils literal"><span class="pre">void</span></tt> or a pointer to a (possibly qualifier) <tt class="docutils literal"><span class="pre">struct</span></tt>
+or <tt class="docutils literal"><span class="pre">class</span></tt> type.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">ARC does not manage pointers of CoreFoundation type (or any of the related
+families of retainable C pointers which interoperate with Objective-C for
+retain/release operation).  In fact, ARC does not even know how to
+distinguish these types from arbitrary C pointer types.  The intent of this
+concept is to filter out some obviously non-object types while leaving a hook
+for later tightening if a means of exhaustively marking CF types is made
+available.</p>
+</div>
+<div class="section" id="auditing-of-c-retainable-pointer-interfaces">
+<span id="arc-misc-c-retainable-audit"></span><h4><a class="toc-backref" href="#id54">Auditing of C retainable pointer interfaces</a><a class="headerlink" href="#auditing-of-c-retainable-pointer-interfaces" title="Permalink to this headline">¶</a></h4>
+<p><span class="when-revised">[beginning Apple 4.0, LLVM 3.1]</span></p>
+<p>A C function may be marked with the <tt class="docutils literal"><span class="pre">cf_audited_transfer</span></tt> attribute to
+express that, except as otherwise marked with attributes, it obeys the
+parameter (consuming vs. non-consuming) and return (retained vs. non-retained)
+conventions for a C function of its name, namely:</p>
+<ul class="simple">
+<li>A parameter of C retainable pointer type is assumed to not be consumed
+unless it is marked with the <tt class="docutils literal"><span class="pre">cf_consumed</span></tt> attribute, and</li>
+<li>A result of C retainable pointer type is assumed to not be returned retained
+unless the function is either marked <tt class="docutils literal"><span class="pre">cf_returns_retained</span></tt> or it follows
+the create/copy naming convention and is not marked
+<tt class="docutils literal"><span class="pre">cf_returns_not_retained</span></tt>.</li>
+</ul>
+<p>A function obeys the <span class="arc-term">create/copy</span> naming convention if its name
+contains as a substring:</p>
+<ul class="simple">
+<li>either “Create” or “Copy” not followed by a lowercase letter, or</li>
+<li>either “create” or “copy” not followed by a lowercase letter and
+not preceded by any letter, whether uppercase or lowercase.</li>
+</ul>
+<p>A second attribute, <tt class="docutils literal"><span class="pre">cf_unknown_transfer</span></tt>, signifies that a function’s
+transfer semantics cannot be accurately captured using any of these
+annotations.  A program is ill-formed if it annotates the same function with
+both <tt class="docutils literal"><span class="pre">cf_audited_transfer</span></tt> and <tt class="docutils literal"><span class="pre">cf_unknown_transfer</span></tt>.</p>
+<p>A pragma is provided to facilitate the mass annotation of interfaces:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="cp">#pragma clang arc_cf_code_audited begin</span>
+<span class="p">...</span>
+<span class="cp">#pragma clang arc_cf_code_audited end</span>
+</pre></div>
+</div>
+<p>All C functions declared within the extent of this pragma are treated as if
+annotated with the <tt class="docutils literal"><span class="pre">cf_audited_transfer</span></tt> attribute unless they otherwise have
+the <tt class="docutils literal"><span class="pre">cf_unknown_transfer</span></tt> attribute.  The pragma is accepted in all language
+modes.  A program is ill-formed if it attempts to change files, whether by
+including a file or ending the current file, within the extent of this pragma.</p>
+<p>It is possible to test for all the features in this section with
+<tt class="docutils literal"><span class="pre">__has_feature(arc_cf_code_audited)</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">A significant inconvenience in ARC programming is the necessity of
+interacting with APIs based around C retainable pointers.  These features are
+designed to make it relatively easy for API authors to quickly review and
+annotate their interfaces, in turn improving the fidelity of tools such as
+the static analyzer and ARC.  The single-file restriction on the pragma is
+designed to eliminate the risk of accidentally annotating some other header’s
+interfaces.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="runtime-support">
+<span id="arc-runtime"></span><h2><a class="toc-backref" href="#id55">Runtime support</a><a class="headerlink" href="#runtime-support" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the interaction between the ARC runtime and the code
+generated by the ARC compiler.  This is not part of the ARC language
+specification; instead, it is effectively a language-specific ABI supplement,
+akin to the “Itanium” generic ABI for C++.</p>
+<p>Ownership qualification does not alter the storage requirements for objects,
+except that it is undefined behavior if a <tt class="docutils literal"><span class="pre">__weak</span></tt> object is inadequately
+aligned for an object of type <tt class="docutils literal"><span class="pre">id</span></tt>.  The other qualifiers may be used on
+explicitly under-aligned memory.</p>
+<p>The runtime tracks <tt class="docutils literal"><span class="pre">__weak</span></tt> objects which holds non-null values.  It is
+undefined behavior to direct modify a <tt class="docutils literal"><span class="pre">__weak</span></tt> object which is being tracked
+by the runtime except through an
+<a class="reference internal" href="#arc-runtime-objc-storeweak"><em>objc_storeWeak</em></a>,
+<a class="reference internal" href="#arc-runtime-objc-destroyweak"><em>objc_destroyWeak</em></a>, or
+<a class="reference internal" href="#arc-runtime-objc-moveweak"><em>objc_moveWeak</em></a> call.</p>
+<p>The runtime must provide a number of new entrypoints which the compiler may
+emit, which are described in the remainder of this section.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p>Several of these functions are semantically equivalent to a message send; we
+emit calls to C functions instead because:</p>
+<ul class="simple">
+<li>the machine code to do so is significantly smaller,</li>
+<li>it is much easier to recognize the C functions in the ARC optimizer, and</li>
+<li>a sufficient sophisticated runtime may be able to avoid the message send in
+common cases.</li>
+</ul>
+<p class="last">Several other of these functions are “fused” operations which can be
+described entirely in terms of other operations.  We use the fused operations
+primarily as a code-size optimization, although in some cases there is also a
+real potential for avoiding redundant operations in the runtime.</p>
+</div>
+<div class="section" id="arc-runtime-objc-autorelease">
+<span id="id-objc-autorelease-id-value"></span><h3><a class="toc-backref" href="#id56"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autorelease(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-autorelease" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it adds the object
+to the innermost autorelease pool exactly as if the object had been sent the
+<tt class="docutils literal"><span class="pre">autorelease</span></tt> message.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-autoreleasepoolpop-void-pool">
+<span id="arc-runtime-objc-autoreleasepoolpop"></span><h3><a class="toc-backref" href="#id57"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_autoreleasePoolPop(void</span> <span class="pre">*pool);</span></tt></a><a class="headerlink" href="#void-objc-autoreleasepoolpop-void-pool" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">pool</span></tt> is the result of a previous call to
+<a class="reference internal" href="#arc-runtime-objc-autoreleasepoolpush"><em>objc_autoreleasePoolPush</em></a> on the
+current thread, where neither <tt class="docutils literal"><span class="pre">pool</span></tt> nor any enclosing pool have previously
+been popped.</p>
+<p>Releases all the objects added to the given autorelease pool and any
+autorelease pools it encloses, then sets the current autorelease pool to the
+pool directly enclosing <tt class="docutils literal"><span class="pre">pool</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-autoreleasepoolpush-void">
+<span id="arc-runtime-objc-autoreleasepoolpush"></span><h3><a class="toc-backref" href="#id58"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">*objc_autoreleasePoolPush(void);</span></tt></a><a class="headerlink" href="#void-objc-autoreleasepoolpush-void" title="Permalink to this headline">¶</a></h3>
+<p>Creates a new autorelease pool that is enclosed by the current pool, makes that
+the current pool, and returns an opaque “handle” to it.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">While the interface is described as an explicit hierarchy of pools, the rules
+allow the implementation to just keep a stack of objects, using the stack
+depth as the opaque pool handle.</p>
+</div>
+</div>
+<div class="section" id="arc-runtime-objc-autoreleasereturnvalue">
+<span id="id-objc-autoreleasereturnvalue-id-value"></span><h3><a class="toc-backref" href="#id59"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_autoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-autoreleasereturnvalue" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it makes a best
+effort to hand off ownership of a retain count on the object to a call to
+<a class="reference internal" href="#arc-runtime-objc-retainautoreleasedreturnvalue"><em>objc_retainAutoreleasedReturnValue</em></a> for the same object in an
+enclosing call frame.  If this is not possible, the object is autoreleased as
+above.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-copyweak-id-dest-id-src">
+<span id="arc-runtime-objc-copyweak"></span><h3><a class="toc-backref" href="#id60"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_copyWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a><a class="headerlink" href="#void-objc-copyweak-id-dest-id-src" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">src</span></tt> is a valid pointer which either contains a null pointer
+or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.  <tt class="docutils literal"><span class="pre">dest</span></tt> is a valid pointer
+which has not been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p><tt class="docutils literal"><span class="pre">dest</span></tt> is initialized to be equivalent to <tt class="docutils literal"><span class="pre">src</span></tt>, potentially registering it
+with the runtime.  Equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">objc_copyWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="kt">id</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">objc_release</span><span class="p">(</span><span class="n">objc_initWeak</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="n">objc_loadWeakRetained</span><span class="p">(</span><span class="n">src</span><span class="p">)));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">src</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-destroyweak-id-object">
+<span id="arc-runtime-objc-destroyweak"></span><h3><a class="toc-backref" href="#id61"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_destroyWeak(id</span> <span class="pre">*object);</span></tt></a><a class="headerlink" href="#void-objc-destroyweak-id-object" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p><tt class="docutils literal"><span class="pre">object</span></tt> is unregistered as a weak object, if it ever was.  The current value
+of <tt class="docutils literal"><span class="pre">object</span></tt> is left unspecified; otherwise, equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">objc_destroyWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">objc_storeWeak</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="nb">nil</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Does not need to be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on
+<tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-initweak">
+<span id="id-objc-initweak-id-object-id-value"></span><h3><a class="toc-backref" href="#id62"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_initWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-initweak" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which has not been registered as
+a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.  <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is a null pointer or the object to which it points has begun
+deallocation, <tt class="docutils literal"><span class="pre">object</span></tt> is zero-initialized.  Otherwise, <tt class="docutils literal"><span class="pre">object</span></tt> is
+registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object pointing to <tt class="docutils literal"><span class="pre">value</span></tt>.  Equivalent to the
+following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_initWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="o">*</span><span class="n">object</span> <span class="o">=</span> <span class="nb">nil</span><span class="p">;</span>
+  <span class="k">return</span> <span class="n">objc_storeWeak</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">value</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Returns the value of <tt class="docutils literal"><span class="pre">object</span></tt> after the call.</p>
+<p>Does not need to be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on
+<tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-loadweak">
+<span id="id-objc-loadweak-id-object"></span><h3><a class="toc-backref" href="#id63"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeak(id</span> <span class="pre">*object);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-loadweak" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p>If <tt class="docutils literal"><span class="pre">object</span></tt> is registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object, and the last value stored
+into <tt class="docutils literal"><span class="pre">object</span></tt> has not yet been deallocated or begun deallocation, retains and
+autoreleases that value and returns it.  Otherwise returns null.  Equivalent to
+the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_loadWeak</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">objc_autorelease</span><span class="p">(</span><span class="n">objc_loadWeakRetained</span><span class="p">(</span><span class="n">object</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+<div class="admonition-rationale admonition">
+<p class="first admonition-title">Rationale</p>
+<p class="last">Loading weak references would be inherently prone to race conditions without
+the retain.</p>
+</div>
+</div>
+<div class="section" id="arc-runtime-objc-loadweakretained">
+<span id="id-objc-loadweakretained-id-object"></span><h3><a class="toc-backref" href="#id64"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_loadWeakRetained(id</span> <span class="pre">*object);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-loadweakretained" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p>If <tt class="docutils literal"><span class="pre">object</span></tt> is registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object, and the last value stored
+into <tt class="docutils literal"><span class="pre">object</span></tt> has not yet been deallocated or begun deallocation, retains
+that value and returns it.  Otherwise returns null.</p>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">object</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-moveweak-id-dest-id-src">
+<span id="arc-runtime-objc-moveweak"></span><h3><a class="toc-backref" href="#id65"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_moveWeak(id</span> <span class="pre">*dest,</span> <span class="pre">id</span> <span class="pre">*src);</span></tt></a><a class="headerlink" href="#void-objc-moveweak-id-dest-id-src" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">src</span></tt> is a valid pointer which either contains a null pointer
+or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.  <tt class="docutils literal"><span class="pre">dest</span></tt> is a valid pointer
+which has not been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.</p>
+<p><tt class="docutils literal"><span class="pre">dest</span></tt> is initialized to be equivalent to <tt class="docutils literal"><span class="pre">src</span></tt>, potentially registering it
+with the runtime.  <tt class="docutils literal"><span class="pre">src</span></tt> may then be left in its original state, in which
+case this call is equivalent to <a class="reference internal" href="#arc-runtime-objc-copyweak"><em>objc_copyWeak</em></a>, or it may be left as null.</p>
+<p>Must be atomic with respect to calls to <tt class="docutils literal"><span class="pre">objc_storeWeak</span></tt> on <tt class="docutils literal"><span class="pre">src</span></tt>.</p>
+</div>
+<div class="section" id="void-objc-release-id-value">
+<span id="arc-runtime-objc-release"></span><h3><a class="toc-backref" href="#id66"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">objc_release(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#void-objc-release-id-value" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it performs a
+release operation exactly as if the object had been sent the <tt class="docutils literal"><span class="pre">release</span></tt>
+message.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retain">
+<span id="id-objc-retain-id-value"></span><h3><a class="toc-backref" href="#id67"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retain(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retain" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it performs a retain
+operation exactly as if the object had been sent the <tt class="docutils literal"><span class="pre">retain</span></tt> message.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautorelease">
+<span id="id-objc-retainautorelease-id-value"></span><h3><a class="toc-backref" href="#id68"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutorelease(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainautorelease" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it performs a retain
+operation followed by an autorelease operation.  Equivalent to the following
+code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_retainAutorelease</span><span class="p">(</span><span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">objc_autorelease</span><span class="p">(</span><span class="n">objc_retain</span><span class="p">(</span><span class="n">value</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautoreleasereturnvalue">
+<span id="id-objc-retainautoreleasereturnvalue-id-value"></span><h3><a class="toc-backref" href="#id69"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleaseReturnValue(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainautoreleasereturnvalue" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it performs a retain
+operation followed by the operation described in
+<a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue"><em>objc_autoreleaseReturnValue</em></a>.
+Equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">id</span> <span class="nf">objc_retainAutoreleaseReturnValue</span><span class="p">(</span><span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">objc_autoreleaseReturnValue</span><span class="p">(</span><span class="n">objc_retain</span><span class="p">(</span><span class="n">value</span><span class="p">));</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainautoreleasedreturnvalue">
+<span id="id-objc-retainautoreleasedreturnvalue-id-value"></span><h3><a class="toc-backref" href="#id70"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainAutoreleasedReturnValue(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainautoreleasedreturnvalue" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, it attempts to
+accept a hand off of a retain count from a call to
+<a class="reference internal" href="#arc-runtime-objc-autoreleasereturnvalue"><em>objc_autoreleaseReturnValue</em></a> on
+<tt class="docutils literal"><span class="pre">value</span></tt> in a recently-called function or something it calls.  If that fails,
+it performs a retain operation exactly like <a class="reference internal" href="#arc-runtime-objc-retain"><em>objc_retain</em></a>.</p>
+<p>Always returns <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+</div>
+<div class="section" id="arc-runtime-objc-retainblock">
+<span id="id-objc-retainblock-id-value"></span><h3><a class="toc-backref" href="#id71"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_retainBlock(id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-retainblock" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid block object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is null, this call has no effect.  Otherwise, if the block pointed
+to by <tt class="docutils literal"><span class="pre">value</span></tt> is still on the stack, it is copied to the heap and the address
+of the copy is returned.  Otherwise a retain operation is performed on the
+block exactly as if it had been sent the <tt class="docutils literal"><span class="pre">retain</span></tt> message.</p>
+</div>
+<div class="section" id="arc-runtime-objc-storestrong">
+<span id="id-objc-storestrong-id-object-id-value"></span><h3><a class="toc-backref" href="#id72"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeStrong(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-storestrong" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer to a <tt class="docutils literal"><span class="pre">__strong</span></tt> object which is
+adequately aligned for a pointer.  <tt class="docutils literal"><span class="pre">value</span></tt> is null or a pointer to a valid
+object.</p>
+<p>Performs the complete sequence for assigning to a <tt class="docutils literal"><span class="pre">__strong</span></tt> object of
+non-block type <a class="footnote-reference" href="#id3" id="id2">[*]</a>.  Equivalent to the following code:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">objc_storeStrong</span><span class="p">(</span><span class="kt">id</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="kt">id</span> <span class="n">value</span><span class="p">)</span> <span class="p">{</span>
+  <span class="kt">id</span> <span class="n">oldValue</span> <span class="o">=</span> <span class="o">*</span><span class="n">object</span><span class="p">;</span>
+  <span class="n">value</span> <span class="o">=</span> <span class="p">[</span><span class="n">value</span> <span class="n">retain</span><span class="p">];</span>
+  <span class="o">*</span><span class="n">object</span> <span class="o">=</span> <span class="n">value</span><span class="p">;</span>
+  <span class="p">[</span><span class="n">oldValue</span> <span class="n">release</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<table class="docutils footnote" frame="void" id="id3" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2">[*]</a></td><td>This does not imply that a <tt class="docutils literal"><span class="pre">__strong</span></tt> object of block type is an
+invalid argument to this function. Rather it implies that an <tt class="docutils literal"><span class="pre">objc_retain</span></tt>
+and not an <tt class="docutils literal"><span class="pre">objc_retainBlock</span></tt> operation will be emitted if the argument is
+a block.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="arc-runtime-objc-storeweak">
+<span id="id-objc-storeweak-id-object-id-value"></span><h3><a class="toc-backref" href="#id73"><tt class="docutils literal"><span class="pre">id</span> <span class="pre">objc_storeWeak(id</span> <span class="pre">*object,</span> <span class="pre">id</span> <span class="pre">value);</span></tt></a><a class="headerlink" href="#arc-runtime-objc-storeweak" title="Permalink to this headline">¶</a></h3>
+<p><em>Precondition:</em> <tt class="docutils literal"><span class="pre">object</span></tt> is a valid pointer which either contains a null
+pointer or has been registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object.  <tt class="docutils literal"><span class="pre">value</span></tt> is null or a
+pointer to a valid object.</p>
+<p>If <tt class="docutils literal"><span class="pre">value</span></tt> is a null pointer or the object to which it points has begun
+deallocation, <tt class="docutils literal"><span class="pre">object</span></tt> is assigned null and unregistered as a <tt class="docutils literal"><span class="pre">__weak</span></tt>
+object.  Otherwise, <tt class="docutils literal"><span class="pre">object</span></tt> is registered as a <tt class="docutils literal"><span class="pre">__weak</span></tt> object or has its
+registration updated to point to <tt class="docutils literal"><span class="pre">value</span></tt>.</p>
+<p>Returns the value of <tt class="docutils literal"><span class="pre">object</span></tt> after the call.</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="Block-ABI-Apple.html">Block Implementation Specification</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AttributeReference.html">Attributes in Clang</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/Block-ABI-Apple.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/Block-ABI-Apple.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/Block-ABI-Apple.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/Block-ABI-Apple.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,909 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Block Implementation Specification — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+    <link rel="next" title="Objective-C Automatic Reference Counting (ARC)" href="AutomaticReferenceCounting.html" />
+    <link rel="prev" title="Language Specification for Blocks" href="BlockLanguageSpec.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Block Implementation Specification</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="BlockLanguageSpec.html">Language Specification for Blocks</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="block-implementation-specification">
+<h1>Block Implementation Specification<a class="headerlink" href="#block-implementation-specification" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#history" id="id1">History</a></li>
+<li><a class="reference internal" href="#high-level" id="id2">High Level</a></li>
+<li><a class="reference internal" href="#imported-variables" id="id3">Imported Variables</a><ul>
+<li><a class="reference internal" href="#imported-const-copy-variables" id="id4">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy variables</a></li>
+<li><a class="reference internal" href="#imported-const-copy-of-block-reference" id="id5">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy of <tt class="docutils literal"><span class="pre">Block</span></tt> reference</a><ul>
+<li><a class="reference internal" href="#importing-attribute-nsobject-variables" id="id6">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#imported-block-marked-variables" id="id7">Imported <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a><ul>
+<li><a class="reference internal" href="#layout-of-block-marked-variables" id="id8">Layout of <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a></li>
+<li><a class="reference internal" href="#access-to-block-variables-from-within-its-lexical-scope" id="id9">Access to <tt class="docutils literal"><span class="pre">__block</span></tt> variables from within its lexical scope</a></li>
+<li><a class="reference internal" href="#importing-block-variables-into-blocks" id="id10">Importing <tt class="docutils literal"><span class="pre">__block</span></tt> variables into <tt class="docutils literal"><span class="pre">Blocks</span></tt></a></li>
+<li><a class="reference internal" href="#importing-attribute-nsobject-block-variables" id="id11">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> <tt class="docutils literal"><span class="pre">__block</span></tt> variables</a></li>
+<li><a class="reference internal" href="#block-escapes" id="id12"><tt class="docutils literal"><span class="pre">__block</span></tt> escapes</a></li>
+<li><a class="reference internal" href="#nesting" id="id13">Nesting</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#objective-c-extensions-to-blocks" id="id14">Objective C Extensions to <tt class="docutils literal"><span class="pre">Blocks</span></tt></a><ul>
+<li><a class="reference internal" href="#importing-objects" id="id15">Importing Objects</a></li>
+<li><a class="reference internal" href="#blocks-as-objects" id="id16"><tt class="docutils literal"><span class="pre">Blocks</span></tt> as Objects</a></li>
+<li><a class="reference internal" href="#weak-block-support" id="id17"><tt class="docutils literal"><span class="pre">__weak</span> <span class="pre">__block</span></tt> Support</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-support" id="id18">C++ Support</a></li>
+<li><a class="reference internal" href="#runtime-helper-functions" id="id19">Runtime Helper Functions</a></li>
+<li><a class="reference internal" href="#copyright" id="id20">Copyright</a></li>
+</ul>
+</div>
+<div class="section" id="history">
+<h2><a class="toc-backref" href="#id1">History</a><a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>2008/7/14 - created.</li>
+<li>2008/8/21 - revised, C++.</li>
+<li>2008/9/24 - add <tt class="docutils literal"><span class="pre">NULL</span></tt> <tt class="docutils literal"><span class="pre">isa</span></tt> field to <tt class="docutils literal"><span class="pre">__block</span></tt> storage.</li>
+<li>2008/10/1 - revise block layout to use a <tt class="docutils literal"><span class="pre">static</span></tt> descriptor structure.</li>
+<li>2008/10/6 - revise block layout to use an unsigned long int flags.</li>
+<li>2008/10/28 - specify use of <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt> for all “Object” types in helper functions.</li>
+<li>2008/10/30 - revise new layout to have invoke function in same place.</li>
+<li>2008/10/30 - add <tt class="docutils literal"><span class="pre">__weak</span></tt> support.</li>
+<li>2010/3/16 - rev for stret return, signature field.</li>
+<li>2010/4/6 - improved wording.</li>
+<li>2013/1/6 - improved wording and converted to rst.</li>
+</ul>
+<p>This document describes the Apple ABI implementation specification of Blocks.</p>
+<p>The first shipping version of this ABI is found in Mac OS X 10.6, and shall be
+referred to as 10.6.ABI. As of 2010/3/16, the following describes the ABI
+contract with the runtime and the compiler, and, as necessary, will be referred
+to as ABI.2010.3.16.</p>
+<p>Since the Apple ABI references symbols from other elements of the system, any
+attempt to use this ABI on systems prior to SnowLeopard is undefined.</p>
+</div>
+<div class="section" id="high-level">
+<h2><a class="toc-backref" href="#id2">High Level</a><a class="headerlink" href="#high-level" title="Permalink to this headline">¶</a></h2>
+<p>The ABI of <tt class="docutils literal"><span class="pre">Blocks</span></tt> consist of their layout and the runtime functions required
+by the compiler.  A <tt class="docutils literal"><span class="pre">Block</span></tt> consists of a structure of the following form:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Block_literal_1</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span> <span class="c1">// initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="p">,</span> <span class="p">...);</span>
+    <span class="k">struct</span> <span class="n">Block_descriptor_1</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>         <span class="c1">// NULL</span>
+        <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>         <span class="c1">// sizeof(struct Block_literal_1)</span>
+        <span class="c1">// optional helper functions</span>
+        <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>     <span class="c1">// IFF (1<<25)</span>
+        <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>             <span class="c1">// IFF (1<<25)</span>
+        <span class="c1">// required ABI.2010.3.16</span>
+        <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">signature</span><span class="p">;</span>                         <span class="c1">// IFF (1<<30)</span>
+    <span class="p">}</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="c1">// imported variables</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The following flags bits are in use thusly for a possible ABI.2010.3.16:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+    <span class="n">BLOCK_HAS_COPY_DISPOSE</span> <span class="o">=</span>  <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">25</span><span class="p">),</span>
+    <span class="n">BLOCK_HAS_CTOR</span> <span class="o">=</span>          <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">26</span><span class="p">),</span> <span class="c1">// helpers have C++ code</span>
+    <span class="n">BLOCK_IS_GLOBAL</span> <span class="o">=</span>         <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">28</span><span class="p">),</span>
+    <span class="n">BLOCK_HAS_STRET</span> <span class="o">=</span>         <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">29</span><span class="p">),</span> <span class="c1">// IFF BLOCK_HAS_SIGNATURE</span>
+    <span class="n">BLOCK_HAS_SIGNATURE</span> <span class="o">=</span>     <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">30</span><span class="p">),</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>In 10.6.ABI the (1<<29) was usually set and was always ignored by the runtime -
+it had been a transitional marker that did not get deleted after the
+transition. This bit is now paired with (1<<30), and represented as the pair
+(3<<30), for the following combinations of valid bit settings, and their
+meanings:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">switch</span> <span class="p">(</span><span class="n">flags</span> <span class="o">&</span> <span class="p">(</span><span class="mi">3</span><span class="o"><<</span><span class="mi">29</span><span class="p">))</span> <span class="p">{</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">0</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>:      <span class="mf">10.6</span><span class="p">.</span><span class="n">ABI</span><span class="p">,</span> <span class="n">no</span> <span class="n">signature</span> <span class="n">field</span> <span class="n">available</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>:      <span class="mf">10.6</span><span class="p">.</span><span class="n">ABI</span><span class="p">,</span> <span class="n">no</span> <span class="n">signature</span> <span class="n">field</span> <span class="n">available</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">2</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>: <span class="n">ABI</span><span class="mf">.2010.3.16</span><span class="p">,</span> <span class="n">regular</span> <span class="n">calling</span> <span class="n">convention</span><span class="p">,</span> <span class="n">presence</span> <span class="n">of</span> <span class="n">signature</span> <span class="n">field</span>
+  <span class="k">case</span> <span class="p">(</span><span class="mi">3</span><span class="o"><<</span><span class="mi">29</span><span class="p">)</span>: <span class="n">ABI</span><span class="mf">.2010.3.16</span><span class="p">,</span> <span class="n">stret</span> <span class="n">calling</span> <span class="n">convention</span><span class="p">,</span> <span class="n">presence</span> <span class="n">of</span> <span class="n">signature</span> <span class="n">field</span><span class="p">,</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The signature field is not always populated.</p>
+<p>The following discussions are presented as 10.6.ABI otherwise.</p>
+<p><tt class="docutils literal"><span class="pre">Block</span></tt> literals may occur within functions where the structure is created in
+stack local memory.  They may also appear as initialization expressions for
+<tt class="docutils literal"><span class="pre">Block</span></tt> variables of global or <tt class="docutils literal"><span class="pre">static</span></tt> local variables.</p>
+<p>When a <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression is evaluated the stack based structure is
+initialized as follows:</p>
+<ol class="arabic simple">
+<li>A <tt class="docutils literal"><span class="pre">static</span></tt> descriptor structure is declared and initialized as follows:</li>
+</ol>
+<blockquote>
+<div><p>a. The <tt class="docutils literal"><span class="pre">invoke</span></tt> function pointer is set to a function that takes the
+<tt class="docutils literal"><span class="pre">Block</span></tt> structure as its first argument and the rest of the arguments (if
+any) to the <tt class="docutils literal"><span class="pre">Block</span></tt> and executes the <tt class="docutils literal"><span class="pre">Block</span></tt> compound statement.</p>
+<p>b. The <tt class="docutils literal"><span class="pre">size</span></tt> field is set to the size of the following <tt class="docutils literal"><span class="pre">Block</span></tt> literal
+structure.</p>
+<p>c. The <tt class="docutils literal"><span class="pre">copy_helper</span></tt> and <tt class="docutils literal"><span class="pre">dispose_helper</span></tt> function pointers are set to
+respective helper functions if they are required by the <tt class="docutils literal"><span class="pre">Block</span></tt> literal.</p>
+</div></blockquote>
+<ol class="arabic" start="2">
+<li><p class="first">A stack (or global) <tt class="docutils literal"><span class="pre">Block</span></tt> literal data structure is created and
+initialized as follows:</p>
+<p>a. The <tt class="docutils literal"><span class="pre">isa</span></tt> field is set to the address of the external
+<tt class="docutils literal"><span class="pre">_NSConcreteStackBlock</span></tt>, which is a block of uninitialized memory supplied
+in <tt class="docutils literal"><span class="pre">libSystem</span></tt>, or <tt class="docutils literal"><span class="pre">_NSConcreteGlobalBlock</span></tt> if this is a static or file
+level <tt class="docutils literal"><span class="pre">Block</span></tt> literal.</p>
+<p>b. The <tt class="docutils literal"><span class="pre">flags</span></tt> field is set to zero unless there are variables imported
+into the <tt class="docutils literal"><span class="pre">Block</span></tt> that need helper functions for program level
+<tt class="docutils literal"><span class="pre">Block_copy()</span></tt> and <tt class="docutils literal"><span class="pre">Block_release()</span></tt> operations, in which case the
+(1<<25) flags bit is set.</p>
+</li>
+</ol>
+<p>As an example, the <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>would cause the following to be created on a 32-bit system:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_1</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_1</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_1</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">__block_descriptor_1</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_1</span><span class="p">),</span> <span class="n">__block_invoke_1</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and where the <tt class="docutils literal"><span class="pre">Block</span></tt> literal itself appears:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+     <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+     <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+     <span class="n">__block_invoke_1</span><span class="p">,</span>
+     <span class="o">&</span><span class="n">__block_descriptor_1</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>A <tt class="docutils literal"><span class="pre">Block</span></tt> imports other <tt class="docutils literal"><span class="pre">Block</span></tt> references, <tt class="docutils literal"><span class="pre">const</span></tt> copies of other
+variables, and variables marked <tt class="docutils literal"><span class="pre">__block</span></tt>.  In Objective-C, variables may
+additionally be objects.</p>
+<p>When a <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression is used as the initial value of a global
+or <tt class="docutils literal"><span class="pre">static</span></tt> local variable, it is initialized as follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_1</span> <span class="n">__block_literal_1</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteGlobalBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">28</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+      <span class="n">__block_invoke_1</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">__block_descriptor_1</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>that is, a different address is provided as the first value and a particular
+(1<<28) bit is set in the <tt class="docutils literal"><span class="pre">flags</span></tt> field, and otherwise it is the same as for
+stack based <tt class="docutils literal"><span class="pre">Block</span></tt> literals.  This is an optimization that can be used for
+any <tt class="docutils literal"><span class="pre">Block</span></tt> literal that imports no <tt class="docutils literal"><span class="pre">const</span></tt> or <tt class="docutils literal"><span class="pre">__block</span></tt> storage
+variables.</p>
+</div>
+<div class="section" id="imported-variables">
+<h2><a class="toc-backref" href="#id3">Imported Variables</a><a class="headerlink" href="#imported-variables" title="Permalink to this headline">¶</a></h2>
+<p>Variables of <tt class="docutils literal"><span class="pre">auto</span></tt> storage class are imported as <tt class="docutils literal"><span class="pre">const</span></tt> copies.  Variables
+of <tt class="docutils literal"><span class="pre">__block</span></tt> storage class are imported as a pointer to an enclosing data
+structure.  Global variables are simply referenced and not considered as
+imported.</p>
+<div class="section" id="imported-const-copy-variables">
+<h3><a class="toc-backref" href="#id4">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy variables</a><a class="headerlink" href="#imported-const-copy-variables" title="Permalink to this headline">¶</a></h3>
+<p>Automatic storage variables not marked with <tt class="docutils literal"><span class="pre">__block</span></tt> are imported as
+<tt class="docutils literal"><span class="pre">const</span></tt> copies.</p>
+<p>The simplest example is that of importing a variable of type <tt class="docutils literal"><span class="pre">int</span></tt>:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">x</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">vv</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"x is %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">x</span><span class="p">);</span> <span class="p">}</span>
+<span class="n">x</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+<span class="n">vv</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>which would be compiled to:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_2</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">const</span> <span class="kt">int</span> <span class="n">x</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_2</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">printf</span><span class="p">(</span><span class="s">"x is %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">_block</span><span class="o">-></span><span class="n">x</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_2</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">__block_descriptor_2</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span><span class="p">)</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="n">__block_literal_2</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+      <span class="n">__block_invoke_2</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">__block_descriptor_2</span><span class="p">,</span>
+      <span class="n">x</span>
+ <span class="p">};</span>
+</pre></div>
+</div>
+<p>In summary, scalars, structures, unions, and function pointers are generally
+imported as <tt class="docutils literal"><span class="pre">const</span></tt> copies with no need for helper functions.</p>
+</div>
+<div class="section" id="imported-const-copy-of-block-reference">
+<h3><a class="toc-backref" href="#id5">Imported <tt class="docutils literal"><span class="pre">const</span></tt> copy of <tt class="docutils literal"><span class="pre">Block</span></tt> reference</a><a class="headerlink" href="#imported-const-copy-of-block-reference" title="Permalink to this headline">¶</a></h3>
+<p>The first case where copy and dispose helper functions are required is for the
+case of when a <tt class="docutils literal"><span class="pre">Block</span></tt> itself is imported.  In this case both a
+<tt class="docutils literal"><span class="pre">copy_helper</span></tt> function and a <tt class="docutils literal"><span class="pre">dispose_helper</span></tt> function are needed.  The
+<tt class="docutils literal"><span class="pre">copy_helper</span></tt> function is passed both the existing stack based pointer and the
+pointer to the new heap version and should call back into the runtime to
+actually do the copy operation on the imported fields within the <tt class="docutils literal"><span class="pre">Block</span></tt>. The
+runtime functions are all described in <a class="reference internal" href="#runtimehelperfunctions"><em>Runtime Helper Functions</em></a>.</p>
+<p>A quick example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">existingBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">vv</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">existingBlock</span><span class="p">();</span> <span class="p">}</span>
+<span class="n">vv</span><span class="p">();</span>
+
+<span class="k">struct</span> <span class="n">__block_literal_3</span> <span class="p">{</span>
+   <span class="p">...;</span> <span class="c1">// existing block</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_literal_3</span> <span class="o">*</span><span class="k">const</span> <span class="n">existingBlock</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_2</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="n">__block</span><span class="o">-></span><span class="n">existingBlock</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="n">__block</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0);</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_4</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">// was _Block_destroy</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">existingBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_4</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_4</span> <span class="o">=</span> <span class="p">{</span>
+    <span class="mi">0</span><span class="p">,</span>
+    <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_4</span><span class="p">),</span>
+    <span class="n">__block_copy_4</span><span class="p">,</span>
+    <span class="n">__block_dispose_4</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>and where said <tt class="docutils literal"><span class="pre">Block</span></tt> is used:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_4</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span>
+      <span class="n">__block_invoke_4</span><span class="p">,</span>
+      <span class="o">&</span> <span class="n">__block_descriptor_4</span>
+      <span class="n">existingBlock</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<div class="section" id="importing-attribute-nsobject-variables">
+<h4><a class="toc-backref" href="#id6">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables</a><a class="headerlink" href="#importing-attribute-nsobject-variables" title="Permalink to this headline">¶</a></h4>
+<p>GCC introduces <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> on structure pointers to mean “this
+is an object”.  This is useful because many low level data structures are
+declared as opaque structure pointers, e.g. <tt class="docutils literal"><span class="pre">CFStringRef</span></tt>, <tt class="docutils literal"><span class="pre">CFArrayRef</span></tt>,
+etc.  When used from C, however, these are still really objects and are the
+second case where that requires copy and dispose helper functions to be
+generated.  The copy helper functions generated by the compiler should use the
+<tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> runtime helper function and in the dispose helper the
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt> runtime helper function should be called.</p>
+<p>For example, <tt class="docutils literal"><span class="pre">Block</span></tt> foo in the following:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Opaque</span> <span class="o">*</span><span class="n">__attribute__</span><span class="p">((</span><span class="n">NSObject</span><span class="p">))</span> <span class="n">objectPointer</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="p">...</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">foo</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span>  <span class="n">CFPrint</span><span class="p">(</span><span class="n">objectPointer</span><span class="p">);</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>would have the following helper functions generated:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">__block_copy_foo</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">objectPointer</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span> <span class="n">objectPointer</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_foo</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">objectPointer</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="imported-block-marked-variables">
+<h3><a class="toc-backref" href="#id7">Imported <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a><a class="headerlink" href="#imported-block-marked-variables" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="layout-of-block-marked-variables">
+<h4><a class="toc-backref" href="#id8">Layout of <tt class="docutils literal"><span class="pre">__block</span></tt> marked variables</a><a class="headerlink" href="#layout-of-block-marked-variables" title="Permalink to this headline">¶</a></h4>
+<p>The compiler must embed variables that are marked <tt class="docutils literal"><span class="pre">__block</span></tt> in a specialized
+structure of the form:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">Block_byref</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="n">typeof</span><span class="p">(</span><span class="n">marked_variable</span><span class="p">)</span> <span class="n">marked_variable</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Variables of certain types require helper functions for when <tt class="docutils literal"><span class="pre">Block_copy()</span></tt>
+and <tt class="docutils literal"><span class="pre">Block_release()</span></tt> are performed upon a referencing <tt class="docutils literal"><span class="pre">Block</span></tt>.  At the “C”
+level only variables that are of type <tt class="docutils literal"><span class="pre">Block</span></tt> or ones that have
+<tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> marked require helper functions.  In Objective-C
+objects require helper functions and in C++ stack based objects require helper
+functions. Variables that require helper functions use the form:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_foo</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="c1">// helper functions called via Block_copy() and Block_release()</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="kt">void</span>  <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="kt">void</span> <span class="o">*</span><span class="p">);</span>
+    <span class="n">typeof</span><span class="p">(</span><span class="n">marked_variable</span><span class="p">)</span> <span class="n">marked_variable</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The structure is initialized such that:</p>
+<blockquote>
+<div><p>a. The <tt class="docutils literal"><span class="pre">forwarding</span></tt> pointer is set to the beginning of its enclosing
+structure.</p>
+<p>b. The <tt class="docutils literal"><span class="pre">size</span></tt> field is initialized to the total size of the enclosing
+structure.</p>
+<p>c. The <tt class="docutils literal"><span class="pre">flags</span></tt> field is set to either 0 if no helper functions are needed
+or (1<<25) if they are.</p>
+<ol class="loweralpha simple" start="4">
+<li>The helper functions are initialized (if present).</li>
+<li>The variable itself is set to its initial value.</li>
+<li>The <tt class="docutils literal"><span class="pre">isa</span></tt> field is set to <tt class="docutils literal"><span class="pre">NULL</span></tt>.</li>
+</ol>
+</div></blockquote>
+</div>
+<div class="section" id="access-to-block-variables-from-within-its-lexical-scope">
+<h4><a class="toc-backref" href="#id9">Access to <tt class="docutils literal"><span class="pre">__block</span></tt> variables from within its lexical scope</a><a class="headerlink" href="#access-to-block-variables-from-within-its-lexical-scope" title="Permalink to this headline">¶</a></h4>
+<p>In order to “move” the variable to the heap upon a <tt class="docutils literal"><span class="pre">copy_helper</span></tt> operation the
+compiler must rewrite access to such a variable to be indirect through the
+structures <tt class="docutils literal"><span class="pre">forwarding</span></tt> pointer.  For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">__block</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="n">i</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>would be rewritten to be:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="p">{</span>
+  <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+  <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+  <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+  <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+  <span class="kt">int</span> <span class="n">captured_i</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">i</span> <span class="o">=</span> <span class="p">{</span> <span class="nb">NULL</span><span class="p">,</span> <span class="o">&</span><span class="n">i</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_i</span><span class="p">),</span> <span class="mi">10</span> <span class="p">};</span>
+
+<span class="n">i</span><span class="p">.</span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_i</span> <span class="o">=</span> <span class="mi">11</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>In the case of a <tt class="docutils literal"><span class="pre">Block</span></tt> reference variable being marked <tt class="docutils literal"><span class="pre">__block</span></tt> the
+helper code generated must use the <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt> routines supplied by the runtime to make the
+copies. For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__block</span> <span class="kt">void</span> <span class="p">(</span><span class="n">voidBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="n">blockA</span><span class="p">;</span>
+<span class="n">voidBlock</span> <span class="o">=</span> <span class="n">blockB</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>would translate into:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">captured_voidBlock</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_keep_helper</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0);</span>
+    <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_dispose_helper</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">param</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_destroy(param->captured_voidBlock, 0);</span>
+    <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">param</span><span class="o">-></span><span class="n">captured_voidBlock</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">)}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="n">voidBlock</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">voidBlock</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">),</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="p">),</span>
+    <span class="p">.</span><span class="n">byref_keep</span><span class="o">=</span><span class="n">_block_byref_keep_helper</span><span class="p">,</span> <span class="p">.</span><span class="n">byref_dispose</span><span class="o">=</span><span class="n">_block_byref_dispose_helper</span><span class="p">,</span>
+    <span class="p">.</span><span class="n">captured_voidBlock</span><span class="o">=</span><span class="n">blockA</span> <span class="p">)};</span>
+
+<span class="n">voidBlock</span><span class="p">.</span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_voidBlock</span> <span class="o">=</span> <span class="n">blockB</span><span class="p">;</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="importing-block-variables-into-blocks">
+<h4><a class="toc-backref" href="#id10">Importing <tt class="docutils literal"><span class="pre">__block</span></tt> variables into <tt class="docutils literal"><span class="pre">Blocks</span></tt></a><a class="headerlink" href="#importing-block-variables-into-blocks" title="Permalink to this headline">¶</a></h4>
+<p>A <tt class="docutils literal"><span class="pre">Block</span></tt> that uses a <tt class="docutils literal"><span class="pre">__block</span></tt> variable in its compound statement body must
+import the variable and emit <tt class="docutils literal"><span class="pre">copy_helper</span></tt> and <tt class="docutils literal"><span class="pre">dispose_helper</span></tt> helper
+functions that, in turn, call back into the runtime to actually copy or release
+the <tt class="docutils literal"><span class="pre">byref</span></tt> data block using the functions <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt>.</p>
+<p>For example:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">__block</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
+<span class="n">functioncall</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span> <span class="p">});</span>
+</pre></div>
+</div>
+<p>would translate to:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>  <span class="c1">// set to NULL</span>
+    <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="p">);</span>
+    <span class="kt">int</span> <span class="n">captured_i</span><span class="p">;</span>
+<span class="p">};</span>
+
+
+<span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">i_holder</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="n">_block</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_i</span> <span class="o">=</span> <span class="mi">10</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_assign_copy(&dst->captured_i, src->captured_i);</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_release(src->captured_i);</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">captured_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_5</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span><span class="p">)</span> <span class="n">__block_copy_5</span><span class="p">,</span> <span class="n">__block_dispose_5</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="n">i</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">isa</span><span class="o">=</span><span class="nb">NULL</span><span class="p">,</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">i</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_i</span><span class="p">),</span> <span class="p">.</span><span class="n">captured_i</span><span class="o">=</span><span class="mi">2</span> <span class="p">)};</span>
+<span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+      <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+      <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+      <span class="n">__block_invoke_5</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">__block_descriptor_5</span><span class="p">,</span>
+      <span class="o">&</span><span class="n">i</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="importing-attribute-nsobject-block-variables">
+<h4><a class="toc-backref" href="#id11">Importing <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> <tt class="docutils literal"><span class="pre">__block</span></tt> variables</a><a class="headerlink" href="#importing-attribute-nsobject-block-variables" title="Permalink to this headline">¶</a></h4>
+<p>A <tt class="docutils literal"><span class="pre">__block</span></tt> variable that is also marked <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> should
+have <tt class="docutils literal"><span class="pre">byref_keep</span></tt> and <tt class="docutils literal"><span class="pre">byref_dispose</span></tt> helper functions that use
+<tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and <tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt>.</p>
+</div>
+<div class="section" id="block-escapes">
+<h4><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">__block</span></tt> escapes</a><a class="headerlink" href="#block-escapes" title="Permalink to this headline">¶</a></h4>
+<p>Because <tt class="docutils literal"><span class="pre">Blocks</span></tt> referencing <tt class="docutils literal"><span class="pre">__block</span></tt> variables may have <tt class="docutils literal"><span class="pre">Block_copy()</span></tt>
+performed upon them the underlying storage for the variables may move to the
+heap.  In Objective-C Garbage Collection Only compilation environments the heap
+used is the garbage collected one and no further action is required.  Otherwise
+the compiler must issue a call to potentially release any heap storage for
+<tt class="docutils literal"><span class="pre">__block</span></tt> variables at all escapes or terminations of their scope.  The call
+should be:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="o">&</span><span class="n">_block_byref_foo</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="nesting">
+<h4><a class="toc-backref" href="#id13">Nesting</a><a class="headerlink" href="#nesting" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">Blocks</span></tt> may contain <tt class="docutils literal"><span class="pre">Block</span></tt> literal expressions.  Any variables used within
+inner blocks are imported into all enclosing <tt class="docutils literal"><span class="pre">Block</span></tt> scopes even if the
+variables are not used. This includes <tt class="docutils literal"><span class="pre">const</span></tt> imports as well as <tt class="docutils literal"><span class="pre">__block</span></tt>
+variables.</p>
+</div>
+</div>
+</div>
+<div class="section" id="objective-c-extensions-to-blocks">
+<h2><a class="toc-backref" href="#id14">Objective C Extensions to <tt class="docutils literal"><span class="pre">Blocks</span></tt></a><a class="headerlink" href="#objective-c-extensions-to-blocks" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="importing-objects">
+<h3><a class="toc-backref" href="#id15">Importing Objects</a><a class="headerlink" href="#importing-objects" title="Permalink to this headline">¶</a></h3>
+<p>Objects should be treated as <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables; all
+<tt class="docutils literal"><span class="pre">copy_helper</span></tt>, <tt class="docutils literal"><span class="pre">dispose_helper</span></tt>, <tt class="docutils literal"><span class="pre">byref_keep</span></tt>, and <tt class="docutils literal"><span class="pre">byref_dispose</span></tt>
+helper functions should use <tt class="docutils literal"><span class="pre">_Block_object_assign</span></tt> and
+<tt class="docutils literal"><span class="pre">_Block_object_dispose</span></tt>.  There should be no code generated that uses
+<tt class="docutils literal"><span class="pre">*-retain</span></tt> or <tt class="docutils literal"><span class="pre">*-release</span></tt> methods.</p>
+</div>
+<div class="section" id="blocks-as-objects">
+<h3><a class="toc-backref" href="#id16"><tt class="docutils literal"><span class="pre">Blocks</span></tt> as Objects</a><a class="headerlink" href="#blocks-as-objects" title="Permalink to this headline">¶</a></h3>
+<p>The compiler will treat <tt class="docutils literal"><span class="pre">Blocks</span></tt> as objects when synthesizing property setters
+and getters, will characterize them as objects when generating garbage
+collection strong and weak layout information in the same manner as objects, and
+will issue strong and weak write-barrier assignments in the same manner as
+objects.</p>
+</div>
+<div class="section" id="weak-block-support">
+<h3><a class="toc-backref" href="#id17"><tt class="docutils literal"><span class="pre">__weak</span> <span class="pre">__block</span></tt> Support</a><a class="headerlink" href="#weak-block-support" title="Permalink to this headline">¶</a></h3>
+<p>Objective-C (and Objective-C++) support the <tt class="docutils literal"><span class="pre">__weak</span></tt> attribute on <tt class="docutils literal"><span class="pre">__block</span></tt>
+variables.  Under normal circumstances the compiler uses the Objective-C runtime
+helper support functions <tt class="docutils literal"><span class="pre">objc_assign_weak</span></tt> and <tt class="docutils literal"><span class="pre">objc_read_weak</span></tt>.  Both
+should continue to be used for all reads and writes of <tt class="docutils literal"><span class="pre">__weak</span> <span class="pre">__block</span></tt>
+variables:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">objc_read_weak</span><span class="p">(</span><span class="o">&</span><span class="n">block</span><span class="o">-></span><span class="n">byref_i</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">i</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">__weak</span></tt> variable is stored in a <tt class="docutils literal"><span class="pre">_block_byref_foo</span></tt> structure and the
+<tt class="docutils literal"><span class="pre">Block</span></tt> has copy and dispose helpers for this structure that call:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span> <span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BYREF</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In turn, the <tt class="docutils literal"><span class="pre">block_byref</span></tt> copy support helpers distinguish between whether
+the <tt class="docutils literal"><span class="pre">__block</span></tt> variable is a <tt class="docutils literal"><span class="pre">Block</span></tt> or not and should either call:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>for something declared as an object or:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dest</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">_block_byref_i</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_BLOCK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>for something declared as a <tt class="docutils literal"><span class="pre">Block</span></tt>.</p>
+<p>A full example follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">__block</span> <span class="n">__weak</span> <span class="n">id</span> <span class="n">obj</span> <span class="o">=</span> <span class="o"><</span><span class="n">initialization</span> <span class="n">expression</span><span class="o">></span><span class="p">;</span>
+<span class="n">functioncall</span><span class="p">(</span><span class="o">^</span><span class="p">{</span> <span class="p">[</span><span class="n">obj</span> <span class="n">somemessage</span><span class="p">];</span> <span class="p">});</span>
+</pre></div>
+</div>
+<p>would translate to:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>  <span class="c1">// uninitialized</span>
+    <span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="o">*</span><span class="n">forwarding</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>   <span class="c1">//refcount;</span>
+    <span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_keep</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">byref_dispose</span><span class="p">)(</span><span class="k">struct</span> <span class="n">_block_byref_i</span> <span class="o">*</span><span class="p">);</span>
+    <span class="n">id</span> <span class="n">captured_obj</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_keep</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0);</span>
+    <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_dispose</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_voidBlock</span> <span class="o">*</span><span class="n">param</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">//_Block_destroy(param->captured_obj, 0);</span>
+    <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">param</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_OBJECT</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span> <span class="o">|</span> <span class="n">BLOCK_BYREF_CALLER</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>for the block <tt class="docutils literal"><span class="pre">byref</span></tt> part and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">struct</span> <span class="n">_block_byref_obj</span> <span class="o">*</span><span class="n">byref_obj</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="p">[</span><span class="n">objc_read_weak</span><span class="p">(</span><span class="o">&</span><span class="n">_block</span><span class="o">-></span><span class="n">byref_obj</span><span class="o">-></span><span class="n">forwarding</span><span class="o">-></span><span class="n">captured_obj</span><span class="p">)</span> <span class="n">somemessage</span><span class="p">];</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_copy_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj);</span>
+     <span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_5</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="c1">//_Block_byref_release(src->byref_obj);</span>
+     <span class="n">_Block_object_dispose</span><span class="p">(</span><span class="n">src</span><span class="o">-></span><span class="n">byref_obj</span><span class="p">,</span> <span class="n">BLOCK_FIELD_IS_BYREF</span> <span class="o">|</span> <span class="n">BLOCK_FIELD_IS_WEAK</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_5</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_5</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_5</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_5</span><span class="p">),</span> <span class="n">__block_copy_5</span><span class="p">,</span> <span class="n">__block_dispose_5</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and within the compound statement:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">truct</span> <span class="n">_block_byref_obj</span> <span class="n">obj</span> <span class="o">=</span> <span class="p">{(</span> <span class="p">.</span><span class="n">forwarding</span><span class="o">=&</span><span class="n">obj</span><span class="p">,</span> <span class="p">.</span><span class="n">flags</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">),</span> <span class="p">.</span><span class="n">size</span><span class="o">=</span><span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_obj</span><span class="p">),</span>
+                 <span class="p">.</span><span class="n">byref_keep</span><span class="o">=</span><span class="n">_block_byref_obj_keep</span><span class="p">,</span> <span class="p">.</span><span class="n">byref_dispose</span><span class="o">=</span><span class="n">_block_byref_obj_dispose</span><span class="p">,</span>
+                 <span class="p">.</span><span class="n">captured_obj</span> <span class="o">=</span> <span class="o"><</span><span class="n">initialization</span> <span class="n">expression</span><span class="o">></span> <span class="p">)};</span>
+
+<span class="n">truct</span> <span class="n">__block_literal_5</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+     <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+     <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+     <span class="n">__block_invoke_5</span><span class="p">,</span>
+     <span class="o">&</span><span class="n">__block_descriptor_5</span><span class="p">,</span>
+     <span class="o">&</span><span class="n">obj</span><span class="p">,</span>        <span class="c1">// a reference to the on-stack structure containing "captured_obj"</span>
+<span class="p">};</span>
+
+
+<span class="n">functioncall</span><span class="p">(</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="p">));</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="c-support">
+<h2><a class="toc-backref" href="#id18">C++ Support</a><a class="headerlink" href="#c-support" title="Permalink to this headline">¶</a></h2>
+<p>Within a block stack based C++ objects are copied into <tt class="docutils literal"><span class="pre">const</span></tt> copies using
+the copy constructor.  It is an error if a stack based C++ object is used within
+a block if it does not have a copy constructor.  In addition both copy and
+destroy helper routines must be synthesized for the block to support the
+<tt class="docutils literal"><span class="pre">Block_copy()</span></tt> operation, and the flags work marked with the (1<<26) bit in
+addition to the (1<<25) bit.  The copy helper should call the constructor using
+appropriate offsets of the variable within the supplied stack based block source
+and heap based destination for all <tt class="docutils literal"><span class="pre">const</span></tt> constructed copies, and similarly
+should call the destructor in the destroy routine.</p>
+<p>As an example, suppose a C++ class <tt class="docutils literal"><span class="pre">FOO</span></tt> existed with a copy constructor.
+Within a code block a stack version of a <tt class="docutils literal"><span class="pre">FOO</span></tt> object is declared and used
+within a <tt class="docutils literal"><span class="pre">Block</span></tt> literal expression:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">{</span>
+    <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">block</span><span class="p">)(</span><span class="kt">void</span><span class="p">)</span> <span class="o">=</span> <span class="o">^</span><span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"%d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">foo</span><span class="p">.</span><span class="n">value</span><span class="p">());</span> <span class="p">};</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The compiler would synthesize:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="p">{</span>
+    <span class="kt">void</span> <span class="o">*</span><span class="n">isa</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">flags</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">invoke</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="p">);</span>
+    <span class="k">struct</span> <span class="n">__block_descriptor_10</span> <span class="o">*</span><span class="n">descriptor</span><span class="p">;</span>
+    <span class="k">const</span> <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">__block_invoke_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">_block</span><span class="p">)</span> <span class="p">{</span>
+   <span class="n">printf</span><span class="p">(</span><span class="s">"%d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">_block</span><span class="o">-></span><span class="n">foo</span><span class="p">.</span><span class="n">value</span><span class="p">());</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_literal_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">foo</span><span class="p">,</span> <span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">__block_dispose_10</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="k">struct</span> <span class="n">__block_descriptor_10</span> <span class="p">{</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">reserved</span><span class="p">;</span>
+    <span class="kt">unsigned</span> <span class="kt">long</span> <span class="kt">int</span> <span class="n">Block_size</span><span class="p">;</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">copy_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="n">src</span><span class="p">);</span>
+    <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">dispose_helper</span><span class="p">)(</span><span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">*</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">__block_descriptor_10</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="k">struct</span> <span class="n">__block_literal_10</span><span class="p">),</span> <span class="n">__block_copy_10</span><span class="p">,</span> <span class="n">__block_dispose_10</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>and the code would be:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">{</span>
+  <span class="n">FOO</span> <span class="n">foo</span><span class="p">;</span>
+  <span class="n">comp_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">foo</span><span class="p">);</span> <span class="c1">// default constructor</span>
+  <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="n">_block_literal</span> <span class="o">=</span> <span class="p">{</span>
+    <span class="o">&</span><span class="n">_NSConcreteStackBlock</span><span class="p">,</span>
+    <span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">25</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">26</span><span class="p">)</span><span class="o">|</span><span class="p">(</span><span class="mi">1</span><span class="o"><<</span><span class="mi">29</span><span class="p">),</span> <span class="o"><</span><span class="n">uninitialized</span><span class="o">></span><span class="p">,</span>
+    <span class="n">__block_invoke_10</span><span class="p">,</span>
+    <span class="o">&</span><span class="n">__block_descriptor_10</span><span class="p">,</span>
+   <span class="p">};</span>
+   <span class="n">comp_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">foo</span><span class="p">,</span> <span class="o">&</span><span class="n">foo</span><span class="p">);</span>  <span class="c1">// const copy into stack version</span>
+   <span class="k">struct</span> <span class="n">__block_literal_10</span> <span class="o">&</span><span class="n">block</span> <span class="o">=</span> <span class="o">&</span><span class="n">_block_literal</span><span class="p">;</span>  <span class="c1">// assign literal to block variable</span>
+   <span class="n">block</span><span class="o">-></span><span class="n">invoke</span><span class="p">(</span><span class="n">block</span><span class="p">);</span>    <span class="c1">// invoke block</span>
+   <span class="n">comp_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">_block_literal</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span> <span class="c1">// destroy stack version of const block copy</span>
+   <span class="n">comp_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">foo</span><span class="p">);</span> <span class="c1">// destroy original version</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>C++ objects stored in <tt class="docutils literal"><span class="pre">__block</span></tt> storage start out on the stack in a
+<tt class="docutils literal"><span class="pre">block_byref</span></tt> data structure as do other variables.  Such objects (if not
+<tt class="docutils literal"><span class="pre">const</span></tt> objects) must support a regular copy constructor.  The <tt class="docutils literal"><span class="pre">block_byref</span></tt>
+data structure will have copy and destroy helper routines synthesized by the
+compiler.  The copy helper will have code created to perform the copy
+constructor based on the initial stack <tt class="docutils literal"><span class="pre">block_byref</span></tt> data structure, and will
+also set the (1<<26) bit in addition to the (1<<25) bit.  The destroy helper
+will have code to do the destructor on the object stored within the supplied
+<tt class="docutils literal"><span class="pre">block_byref</span></tt> heap data structure.  For example,</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__block</span> <span class="n">FOO</span> <span class="n">blockStorageFoo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>requires the normal constructor for the embedded <tt class="docutils literal"><span class="pre">blockStorageFoo</span></tt> object:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span> <span class="n">_block_byref_blockStorageFoo</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>and at scope termination the destructor:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span> <span class="n">_block_byref_blockStorageFoo</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Note that the forwarding indirection is <em>NOT</em> used.</p>
+<p>The compiler would need to generate (if used from a block literal) the following
+copy/dispose helpers:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">_block_byref_obj_keep</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">dst</span><span class="p">,</span> <span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_ctor</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">,</span> <span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">_block_byref_obj_dispose</span><span class="p">(</span><span class="k">struct</span> <span class="n">_block_byref_blockStorageFoo</span> <span class="o">*</span><span class="n">src</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">FOO_dtor</span><span class="p">(</span><span class="o">&</span><span class="n">src</span><span class="o">-></span><span class="n">blockStorageFoo</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>for the appropriately named constructor and destructor for the class/struct
+<tt class="docutils literal"><span class="pre">FOO</span></tt>.</p>
+<p>To support member variable and function access the compiler will synthesize a
+<tt class="docutils literal"><span class="pre">const</span></tt> pointer to a block version of the <tt class="docutils literal"><span class="pre">this</span></tt> pointer.</p>
+</div>
+<div class="section" id="runtime-helper-functions">
+<span id="runtimehelperfunctions"></span><h2><a class="toc-backref" href="#id19">Runtime Helper Functions</a><a class="headerlink" href="#runtime-helper-functions" title="Permalink to this headline">¶</a></h2>
+<p>The runtime helper functions are described in
+<tt class="docutils literal"><span class="pre">/usr/local/include/Block_private.h</span></tt>.  To summarize their use, a <tt class="docutils literal"><span class="pre">Block</span></tt>
+requires copy/dispose helpers if it imports any block variables, <tt class="docutils literal"><span class="pre">__block</span></tt>
+storage variables, <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables, or C++ <tt class="docutils literal"><span class="pre">const</span></tt>
+copied objects with constructor/destructors.  The (1<<26) bit is set and
+functions are generated.</p>
+<p>The block copy helper function should, for each of the variables of the type
+mentioned above, call:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_assign</span><span class="p">(</span><span class="o">&</span><span class="n">dst</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">src</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">BLOCK_FIELD_</span><span class="o"><</span><span class="n">appropo</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>in the copy helper and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">_Block_object_dispose</span><span class="p">(</span><span class="o">-></span><span class="n">target</span><span class="p">,</span> <span class="n">BLOCK_FIELD_</span><span class="o"><</span><span class="n">appropo</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>in the dispose helper where <tt class="docutils literal"><span class="pre"><appropo></span></tt> is:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="p">{</span>
+    <span class="n">BLOCK_FIELD_IS_OBJECT</span>   <span class="o">=</span>  <span class="mi">3</span><span class="p">,</span>  <span class="c1">// id, NSObject, __attribute__((NSObject)), block, ...</span>
+    <span class="n">BLOCK_FIELD_IS_BLOCK</span>    <span class="o">=</span>  <span class="mi">7</span><span class="p">,</span>  <span class="c1">// a block variable</span>
+    <span class="n">BLOCK_FIELD_IS_BYREF</span>    <span class="o">=</span>  <span class="mi">8</span><span class="p">,</span>  <span class="c1">// the on stack structure holding the __block variable</span>
+
+    <span class="n">BLOCK_FIELD_IS_WEAK</span>     <span class="o">=</span> <span class="mi">16</span><span class="p">,</span>  <span class="c1">// declared __weak</span>
+
+    <span class="n">BLOCK_BYREF_CALLER</span>      <span class="o">=</span> <span class="mi">128</span><span class="p">,</span> <span class="c1">// called from byref copy/dispose helpers</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>and of course the constructors/destructors for <tt class="docutils literal"><span class="pre">const</span></tt> copied C++ objects.</p>
+<p>The <tt class="docutils literal"><span class="pre">block_byref</span></tt> data structure similarly requires copy/dispose helpers for
+block variables, <tt class="docutils literal"><span class="pre">__attribute__((NSObject))</span></tt> variables, or C++ <tt class="docutils literal"><span class="pre">const</span></tt>
+copied objects with constructor/destructors, and again the (1<<26) bit is set
+and functions are generated in the same manner.</p>
+<p>Under ObjC we allow <tt class="docutils literal"><span class="pre">__weak</span></tt> as an attribute on <tt class="docutils literal"><span class="pre">__block</span></tt> variables, and
+this causes the addition of <tt class="docutils literal"><span class="pre">BLOCK_FIELD_IS_WEAK</span></tt> orred onto the
+<tt class="docutils literal"><span class="pre">BLOCK_FIELD_IS_BYREF</span></tt> flag when copying the <tt class="docutils literal"><span class="pre">block_byref</span></tt> structure in the
+<tt class="docutils literal"><span class="pre">Block</span></tt> copy helper, and onto the <tt class="docutils literal"><span class="pre">BLOCK_FIELD_<appropo></span></tt> field within the
+<tt class="docutils literal"><span class="pre">block_byref</span></tt> copy/dispose helper calls.</p>
+<p>The prototypes, and summary, of the helper functions are:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cm">/* Certain field types require runtime assistance when being copied to the</span>
+<span class="cm">   heap.  The following function is used to copy fields of types: blocks,</span>
+<span class="cm">   pointers to byref structures, and objects (including</span>
+<span class="cm">   __attribute__((NSObject)) pointers.  BLOCK_FIELD_IS_WEAK is orthogonal to</span>
+<span class="cm">   the other choices which are mutually exclusive.  Only in a Block copy</span>
+<span class="cm">   helper will one see BLOCK_FIELD_IS_BYREF.</span>
+<span class="cm">*/</span>
+<span class="kt">void</span> <span class="nf">_Block_object_assign</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">destAddr</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="k">const</span> <span class="kt">int</span> <span class="n">flags</span><span class="p">);</span>
+
+<span class="cm">/* Similarly a compiler generated dispose helper needs to call back for each</span>
+<span class="cm">   field of the byref data structure.  (Currently the implementation only</span>
+<span class="cm">   packs one field into the byref structure but in principle there could be</span>
+<span class="cm">   more).  The same flags used in the copy helper should be used for each</span>
+<span class="cm">   call generated to this function:</span>
+<span class="cm">*/</span>
+<span class="kt">void</span> <span class="nf">_Block_object_dispose</span><span class="p">(</span><span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">object</span><span class="p">,</span> <span class="k">const</span> <span class="kt">int</span> <span class="n">flags</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="copyright">
+<h2><a class="toc-backref" href="#id20">Copyright</a><a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h2>
+<p>Copyright 2008-2010 Apple, Inc.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:</p>
+<p>The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.</p>
+<p>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="BlockLanguageSpec.html">Language Specification for Blocks</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AutomaticReferenceCounting.html">Objective-C Automatic Reference Counting (ARC)</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/BlockLanguageSpec.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/BlockLanguageSpec.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/BlockLanguageSpec.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/BlockLanguageSpec.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,372 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Language Specification for Blocks — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="up" title="Clang Language Extensions" href="LanguageExtensions.html" />
+    <link rel="next" title="Block Implementation Specification" href="Block-ABI-Apple.html" />
+    <link rel="prev" title="Objective-C Literals" href="ObjectiveCLiterals.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Language Specification for Blocks</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="ObjectiveCLiterals.html">Objective-C Literals</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Block-ABI-Apple.html">Block Implementation Specification</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="language-specification-for-blocks">
+<h1>Language Specification for Blocks<a class="headerlink" href="#language-specification-for-blocks" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#revisions" id="id1">Revisions</a></li>
+<li><a class="reference internal" href="#overview" id="id2">Overview</a></li>
+<li><a class="reference internal" href="#the-block-type" id="id3">The Block Type</a></li>
+<li><a class="reference internal" href="#block-variable-declarations" id="id4">Block Variable Declarations</a></li>
+<li><a class="reference internal" href="#block-literal-expressions" id="id5">Block Literal Expressions</a></li>
+<li><a class="reference internal" href="#the-invoke-operator" id="id6">The Invoke Operator</a></li>
+<li><a class="reference internal" href="#the-copy-and-release-operations" id="id7">The Copy and Release Operations</a></li>
+<li><a class="reference internal" href="#the-block-storage-qualifier" id="id8">The <tt class="docutils literal"><span class="pre">__block</span></tt> Storage Qualifier</a></li>
+<li><a class="reference internal" href="#control-flow" id="id9">Control Flow</a></li>
+<li><a class="reference internal" href="#objective-c-extensions" id="id10">Objective-C Extensions</a></li>
+<li><a class="reference internal" href="#c-extensions" id="id11">C++ Extensions</a></li>
+</ul>
+</div>
+<div class="section" id="revisions">
+<h2><a class="toc-backref" href="#id1">Revisions</a><a class="headerlink" href="#revisions" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>2008/2/25 — created</li>
+<li>2008/7/28 — revised, <tt class="docutils literal"><span class="pre">__block</span></tt> syntax</li>
+<li>2008/8/13 — revised, Block globals</li>
+<li>2008/8/21 — revised, C++ elaboration</li>
+<li>2008/11/1 — revised, <tt class="docutils literal"><span class="pre">__weak</span></tt> support</li>
+<li>2009/1/12 — revised, explicit return types</li>
+<li>2009/2/10 — revised, <tt class="docutils literal"><span class="pre">__block</span></tt> objects need retain</li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id2">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>A new derived type is introduced to C and, by extension, Objective-C,
+C++, and Objective-C++</p>
+</div>
+<div class="section" id="the-block-type">
+<h2><a class="toc-backref" href="#id3">The Block Type</a><a class="headerlink" href="#the-block-type" title="Permalink to this headline">¶</a></h2>
+<p>Like function types, the <span class="block-term">Block type</span> is a pair consisting
+of a result value type and a list of parameter types very similar to a
+function type. Blocks are intended to be used much like functions with
+the key distinction being that in addition to executable code they
+also contain various variable bindings to automatic (stack) or managed
+(heap) memory.</p>
+<p>The abstract declarator,</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="p">)(</span><span class="kt">char</span><span class="p">,</span> <span class="kt">float</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>describes a reference to a Block that, when invoked, takes two
+parameters, the first of type char and the second of type float, and
+returns a value of type int.  The Block referenced is of opaque data
+that may reside in automatic (stack) memory, global memory, or heap
+memory.</p>
+</div>
+<div class="section" id="block-variable-declarations">
+<h2><a class="toc-backref" href="#id4">Block Variable Declarations</a><a class="headerlink" href="#block-variable-declarations" title="Permalink to this headline">¶</a></h2>
+<p>A <span class="block-term">variable with Block type</span> is declared using function
+pointer style notation substituting <tt class="docutils literal"><span class="pre">^</span></tt> for <tt class="docutils literal"><span class="pre">*</span></tt>. The following are
+valid Block variable declarations:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">blockReturningVoidWithVoidArgument</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="n">blockReturningIntWithIntAndCharArguments</span><span class="p">)(</span><span class="kt">int</span><span class="p">,</span> <span class="kt">char</span><span class="p">);</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">arrayOfTenBlocksReturningVoidWithIntArgument</span><span class="p">[</span><span class="mi">10</span><span class="p">])(</span><span class="kt">int</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Variadic <tt class="docutils literal"><span class="pre">...</span></tt> arguments are supported. [variadic.c] A Block that
+takes no arguments must specify void in the argument list [voidarg.c].
+An empty parameter list does not represent, as K&R provide, an
+unspecified argument list.  Note: both gcc and clang support K&R style
+as a convenience.</p>
+<p>A Block reference may be cast to a pointer of arbitrary type and vice
+versa. [cast.c] A Block reference may not be dereferenced via the
+pointer dereference operator <tt class="docutils literal"><span class="pre">*</span></tt>, and thus a Block’s size may not be
+computed at compile time. [sizeof.c]</p>
+</div>
+<div class="section" id="block-literal-expressions">
+<h2><a class="toc-backref" href="#id5">Block Literal Expressions</a><a class="headerlink" href="#block-literal-expressions" title="Permalink to this headline">¶</a></h2>
+<p>A <span class="block-term">Block literal expression</span> produces a reference to a
+Block. It is introduced by the use of the <tt class="docutils literal"><span class="pre">^</span></tt> token as a unary
+operator.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">Block_literal_expression</span> <span class="o">::=</span>   <span class="o">^</span> <span class="n">block_decl</span> <span class="n">compound_statement_body</span>
+<span class="n">block_decl</span> <span class="o">::=</span>
+<span class="n">block_decl</span> <span class="o">::=</span> <span class="n">parameter_list</span>
+<span class="n">block_decl</span> <span class="o">::=</span> <span class="n">type_expression</span>
+</pre></div>
+</div>
+<p>where type expression is extended to allow <tt class="docutils literal"><span class="pre">^</span></tt> as a Block reference
+(pointer) where <tt class="docutils literal"><span class="pre">*</span></tt> is allowed as a function reference (pointer).</p>
+<p>The following Block literal:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="kt">void</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>produces a reference to a Block with no arguments with no return value.</p>
+<p>The return type is optional and is inferred from the return
+statements. If the return statements return a value, they all must
+return a value of the same type. If there is no value returned the
+inferred type of the Block is void; otherwise it is the type of the
+return statement value.</p>
+<p>If the return type is omitted and the argument list is <tt class="docutils literal"><span class="pre">(</span> <span class="pre">void</span> <span class="pre">)</span></tt>,
+the <tt class="docutils literal"><span class="pre">(</span> <span class="pre">void</span> <span class="pre">)</span></tt> argument list may also be omitted.</p>
+<p>So:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="p">(</span> <span class="kt">void</span> <span class="p">)</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="p">{</span> <span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>are exactly equivalent constructs for the same expression.</p>
+<p>The type_expression extends C expression parsing to accommodate Block
+reference declarations as it accommodates function pointer
+declarations.</p>
+<p>Given:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="nf">int</span> <span class="p">(</span><span class="o">*</span><span class="n">pointerToFunctionThatReturnsIntWithCharArg</span><span class="p">)(</span><span class="kt">char</span><span class="p">);</span>
+<span class="n">pointerToFunctionThatReturnsIntWithCharArg</span> <span class="n">functionPointer</span><span class="p">;</span>
+<span class="o">^</span> <span class="n">pointerToFunctionThatReturnsIntWithCharArg</span> <span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>and:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span> <span class="kt">int</span> <span class="p">((</span><span class="o">*</span><span class="p">)(</span><span class="kt">float</span> <span class="n">x</span><span class="p">))(</span><span class="kt">char</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>are equivalent expressions, as is:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="o">^</span><span class="p">(</span><span class="kt">float</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">functionPointer</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>[returnfunctionptr.c]</p>
+<p>The compound statement body establishes a new lexical scope within
+that of its parent. Variables used within the scope of the compound
+statement are bound to the Block in the normal manner with the
+exception of those in automatic (stack) storage. Thus one may access
+functions and global variables as one would expect, as well as static
+local variables. [testme]</p>
+<p>Local automatic (stack) variables referenced within the compound
+statement of a Block are imported and captured by the Block as const
+copies. The capture (binding) is performed at the time of the Block
+literal expression evaluation.</p>
+<p>The compiler is not required to capture a variable if it can prove
+that no references to the variable will actually be evaluated.
+Programmers can force a variable to be captured by referencing it in a
+statement at the beginning of the Block, like so:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="n">foo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>This matters when capturing the variable has side-effects, as it can
+in Objective-C or C++.</p>
+<p>The lifetime of variables declared in a Block is that of a function;
+each activation frame contains a new copy of variables declared within
+the local scope of the Block. Such variable declarations should be
+allowed anywhere [testme] rather than only when C99 parsing is
+requested, including for statements. [testme]</p>
+<p>Block literal expressions may occur within Block literal expressions
+(nest) and all variables captured by any nested blocks are implicitly
+also captured in the scopes of their enclosing Blocks.</p>
+<p>A Block literal expression may be used as the initialization value for
+Block variables at global or local static scope.</p>
+</div>
+<div class="section" id="the-invoke-operator">
+<h2><a class="toc-backref" href="#id6">The Invoke Operator</a><a class="headerlink" href="#the-invoke-operator" title="Permalink to this headline">¶</a></h2>
+<p>Blocks are <span class="block-term">invoked</span> using function call syntax with a
+list of expression parameters of types corresponding to the
+declaration and returning a result type also according to the
+declaration. Given:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="n">x</span><span class="p">)(</span><span class="kt">char</span><span class="p">);</span>
+<span class="kt">void</span> <span class="p">(</span><span class="o">^</span><span class="n">z</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
+<span class="kt">int</span> <span class="p">(</span><span class="o">^</span><span class="p">(</span><span class="o">*</span><span class="n">y</span><span class="p">))(</span><span class="kt">char</span><span class="p">)</span> <span class="o">=</span> <span class="o">&</span><span class="n">x</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>the following are all legal Block invocations:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">x</span><span class="p">(</span><span class="sc">'a'</span><span class="p">);</span>
+<span class="p">(</span><span class="o">*</span><span class="n">y</span><span class="p">)(</span><span class="sc">'a'</span><span class="p">);</span>
+<span class="p">(</span><span class="nb">true</span> <span class="o">?</span> <span class="n">x</span> <span class="o">:</span> <span class="o">*</span><span class="n">y</span><span class="p">)(</span><span class="sc">'a'</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-copy-and-release-operations">
+<h2><a class="toc-backref" href="#id7">The Copy and Release Operations</a><a class="headerlink" href="#the-copy-and-release-operations" title="Permalink to this headline">¶</a></h2>
+<p>The compiler and runtime provide <span class="block-term">copy</span> and
+<span class="block-term">release</span> operations for Block references that create and,
+in matched use, release allocated storage for referenced Blocks.</p>
+<p>The copy operation <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> is styled as a function that takes
+an arbitrary Block reference and returns a Block reference of the same
+type. The release operation, <tt class="docutils literal"><span class="pre">Block_release()</span></tt>, is styled as a
+function that takes an arbitrary Block reference and, if dynamically
+matched to a Block copy operation, allows recovery of the referenced
+allocated memory.</p>
+</div>
+<div class="section" id="the-block-storage-qualifier">
+<h2><a class="toc-backref" href="#id8">The <tt class="docutils literal"><span class="pre">__block</span></tt> Storage Qualifier</a><a class="headerlink" href="#the-block-storage-qualifier" title="Permalink to this headline">¶</a></h2>
+<p>In addition to the new Block type we also introduce a new storage
+qualifier, <span class="block-term">__block</span>, for local variables. [testme: a
+__block declaration within a block literal] The <tt class="docutils literal"><span class="pre">__block</span></tt> storage
+qualifier is mutually exclusive to the existing local storage
+qualifiers auto, register, and static. [testme] Variables qualified by
+<tt class="docutils literal"><span class="pre">__block</span></tt> act as if they were in allocated storage and this storage
+is automatically recovered after last use of said variable.  An
+implementation may choose an optimization where the storage is
+initially automatic and only “moved” to allocated (heap) storage upon
+a Block_copy of a referencing Block.  Such variables may be mutated as
+normal variables are.</p>
+<p>In the case where a <tt class="docutils literal"><span class="pre">__block</span></tt> variable is a Block one must assume
+that the <tt class="docutils literal"><span class="pre">__block</span></tt> variable resides in allocated storage and as such
+is assumed to reference a Block that is also in allocated storage
+(that it is the result of a <tt class="docutils literal"><span class="pre">Block_copy</span></tt> operation).  Despite this
+there is no provision to do a <tt class="docutils literal"><span class="pre">Block_copy</span></tt> or a <tt class="docutils literal"><span class="pre">Block_release</span></tt> if
+an implementation provides initial automatic storage for Blocks.  This
+is due to the inherent race condition of potentially several threads
+trying to update the shared variable and the need for synchronization
+around disposing of older values and copying new ones.  Such
+synchronization is beyond the scope of this language specification.</p>
+</div>
+<div class="section" id="control-flow">
+<h2><a class="toc-backref" href="#id9">Control Flow</a><a class="headerlink" href="#control-flow" title="Permalink to this headline">¶</a></h2>
+<p>The compound statement of a Block is treated much like a function body
+with respect to control flow in that goto, break, and continue do not
+escape the Block.  Exceptions are treated <em>normally</em> in that when
+thrown they pop stack frames until a catch clause is found.</p>
+</div>
+<div class="section" id="objective-c-extensions">
+<h2><a class="toc-backref" href="#id10">Objective-C Extensions</a><a class="headerlink" href="#objective-c-extensions" title="Permalink to this headline">¶</a></h2>
+<p>Objective-C extends the definition of a Block reference type to be
+that also of id.  A variable or expression of Block type may be
+messaged or used as a parameter wherever an id may be. The converse is
+also true. Block references may thus appear as properties and are
+subject to the assign, retain, and copy attribute logic that is
+reserved for objects.</p>
+<p>All Blocks are constructed to be Objective-C objects regardless of
+whether the Objective-C runtime is operational in the program or
+not. Blocks using automatic (stack) memory are objects and may be
+messaged, although they may not be assigned into <tt class="docutils literal"><span class="pre">__weak</span></tt> locations
+if garbage collection is enabled.</p>
+<p>Within a Block literal expression within a method definition
+references to instance variables are also imported into the lexical
+scope of the compound statement. These variables are implicitly
+qualified as references from self, and so self is imported as a const
+copy. The net effect is that instance variables can be mutated.</p>
+<p>The <span class="block-term">Block_copy</span> operator retains all objects held in
+variables of automatic storage referenced within the Block expression
+(or form strong references if running under garbage collection).
+Object variables of <tt class="docutils literal"><span class="pre">__block</span></tt> storage type are assumed to hold
+normal pointers with no provision for retain and release messages.</p>
+<p>Foundation defines (and supplies) <tt class="docutils literal"><span class="pre">-copy</span></tt> and <tt class="docutils literal"><span class="pre">-release</span></tt> methods for
+Blocks.</p>
+<p>In the Objective-C and Objective-C++ languages, we allow the
+<tt class="docutils literal"><span class="pre">__weak</span></tt> specifier for <tt class="docutils literal"><span class="pre">__block</span></tt> variables of object type.  If
+garbage collection is not enabled, this qualifier causes these
+variables to be kept without retain messages being sent. This
+knowingly leads to dangling pointers if the Block (or a copy) outlives
+the lifetime of this object.</p>
+<p>In garbage collected environments, the <tt class="docutils literal"><span class="pre">__weak</span></tt> variable is set to
+nil when the object it references is collected, as long as the
+<tt class="docutils literal"><span class="pre">__block</span></tt> variable resides in the heap (either by default or via
+<tt class="docutils literal"><span class="pre">Block_copy()</span></tt>).  The initial Apple implementation does in fact
+start <tt class="docutils literal"><span class="pre">__block</span></tt> variables on the stack and migrate them to the heap
+only as a result of a <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> operation.</p>
+<p>It is a runtime error to attempt to assign a reference to a
+stack-based Block into any storage marked <tt class="docutils literal"><span class="pre">__weak</span></tt>, including
+<tt class="docutils literal"><span class="pre">__weak</span></tt> <tt class="docutils literal"><span class="pre">__block</span></tt> variables.</p>
+</div>
+<div class="section" id="c-extensions">
+<h2><a class="toc-backref" href="#id11">C++ Extensions</a><a class="headerlink" href="#c-extensions" title="Permalink to this headline">¶</a></h2>
+<p>Block literal expressions within functions are extended to allow const
+use of C++ objects, pointers, or references held in automatic storage.</p>
+<p>As usual, within the block, references to captured variables become
+const-qualified, as if they were references to members of a const
+object.  Note that this does not change the type of a variable of
+reference type.</p>
+<p>For example, given a class Foo:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">Foo</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">&</span><span class="n">fooRef</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">*</span><span class="n">fooPtr</span> <span class="o">=</span> <span class="o">&</span><span class="n">foo</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>A Block that referenced these variables would import the variables as
+const variations:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">const</span> <span class="n">Foo</span> <span class="n">block_foo</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">&</span><span class="n">block_fooRef</span> <span class="o">=</span> <span class="n">fooRef</span><span class="p">;</span>
+<span class="n">Foo</span> <span class="o">*</span><span class="k">const</span> <span class="n">block_fooPtr</span> <span class="o">=</span> <span class="n">fooPtr</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Captured variables are copied into the Block at the instant of
+evaluating the Block literal expression.  They are also copied when
+calling <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> on a Block allocated on the stack.  In both
+cases, they are copied as if the variable were const-qualified, and
+it’s an error if there’s no such constructor.</p>
+<p>Captured variables in Blocks on the stack are destroyed when control
+leaves the compound statement that contains the Block literal
+expression.  Captured variables in Blocks on the heap are destroyed
+when the reference count of the Block drops to zero.</p>
+<p>Variables declared as residing in <tt class="docutils literal"><span class="pre">__block</span></tt> storage may be initially
+allocated in the heap or may first appear on the stack and be copied
+to the heap as a result of a <tt class="docutils literal"><span class="pre">Block_copy()</span></tt> operation. When copied
+from the stack, <tt class="docutils literal"><span class="pre">__block</span></tt> variables are copied using their normal
+qualification (i.e. without adding const).  In C++11, <tt class="docutils literal"><span class="pre">__block</span></tt>
+variables are copied as x-values if that is possible, then as l-values
+if not; if both fail, it’s an error.  The destructor for any initial
+stack-based version is called at the variable’s normal end of scope.</p>
+<p>References to <tt class="docutils literal"><span class="pre">this</span></tt>, as well as references to non-static members of
+any enclosing class, are evaluated by capturing <tt class="docutils literal"><span class="pre">this</span></tt> just like a
+normal variable of C pointer type.</p>
+<p>Member variables that are Blocks may not be overloaded by the types of
+their arguments.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="ObjectiveCLiterals.html">Objective-C Literals</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Block-ABI-Apple.html">Block Implementation Specification</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/ClangCheck.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ClangCheck.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ClangCheck.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ClangCheck.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,103 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>ClangCheck — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="next" title="ClangFormat" href="ClangFormat.html" />
+    <link rel="prev" title="Overview" href="ClangTools.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>ClangCheck</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="ClangTools.html">Overview</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangFormat.html">ClangFormat</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clangcheck">
+<h1>ClangCheck<a class="headerlink" href="#clangcheck" title="Permalink to this headline">¶</a></h1>
+<p><cite>ClangCheck</cite> is a small wrapper around <a class="reference internal" href="LibTooling.html"><em>LibTooling</em></a> which can be used to
+do basic error checking and AST dumping.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat <span class="s"><<EOF > snippet.cc</span>
+<span class="gp">></span><span class="s"> void f() {</span>
+<span class="gp">></span><span class="s">   int a = 0</span>
+<span class="gp">></span><span class="s"> }</span>
+<span class="gp">></span><span class="s"> EOF</span>
+<span class="gp">$</span> ~/clang/build/bin/clang-check snippet.cc -ast-dump --
+<span class="go">Processing: /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc.</span>
+<span class="go">/Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: error: expected ';' at end of</span>
+<span class="go">      declaration</span>
+<span class="go">  int a = 0</span>
+<span class="go">           ^</span>
+<span class="go">           ;</span>
+<span class="go">(TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>></span>
+<span class="go">  (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128')</span>
+<span class="go">  (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned __int128')</span>
+<span class="go">  (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list '__va_list_tag [1]')</span>
+<span class="go">  (FunctionDecl 0x7ff3a302a8d0 </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> f 'void (void)'</span>
+<span class="go">    (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1></span>
+<span class="go">      (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1></span>
+<span class="go">        (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int'</span>
+<span class="go">          (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0))))))</span>
+<span class="go">1 error generated.</span>
+<span class="go">Error while processing snippet.cc.</span>
+</pre></div>
+</div>
+<p>The ‘–’ at the end is important as it prevents <strong class="program">clang-check</strong> from
+searching for a compilation database. For more information on how to setup and
+use <strong class="program">clang-check</strong> in a project, see <a class="reference internal" href="HowToSetupToolingForLLVM.html"><em>How To Setup Clang Tooling For LLVM</em></a>.</p>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="ClangTools.html">Overview</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangFormat.html">ClangFormat</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/ClangFormat.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ClangFormat.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ClangFormat.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ClangFormat.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,232 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>ClangFormat — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="next" title="Clang-Format Style Options" href="ClangFormatStyleOptions.html" />
+    <link rel="prev" title="ClangCheck" href="ClangCheck.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>ClangFormat</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="ClangCheck.html">ClangCheck</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangFormatStyleOptions.html">Clang-Format Style Options</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clangformat">
+<h1>ClangFormat<a class="headerlink" href="#clangformat" title="Permalink to this headline">¶</a></h1>
+<p><cite>ClangFormat</cite> describes a set of tools that are built on top of
+<a class="reference internal" href="LibFormat.html"><em>LibFormat</em></a>. It can support your workflow in a variety of ways including a
+standalone tool and editor integrations.</p>
+<div class="section" id="standalone-tool">
+<h2>Standalone Tool<a class="headerlink" href="#standalone-tool" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">clang-format</strong> is located in <cite>clang/tools/clang-format</cite> and can be used
+to format C/C++/Obj-C code.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang-format -help
+<span class="go">OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf code.</span>
+
+<span class="go">If no arguments are specified, it formats the code from standard input</span>
+<span class="go">and writes the result to the standard output.</span>
+<span class="go">If <file>s are given, it reformats the files. If -i is specified</span>
+<span class="go">together with <file>s, the files are edited in-place. Otherwise, the</span>
+<span class="go">result is written to the standard output.</span>
+
+<span class="go">USAGE: clang-format [options] [<file> ...]</span>
+
+<span class="go">OPTIONS:</span>
+
+<span class="go">Clang-format options:</span>
+
+<span class="go">  -assume-filename=<string> - When reading from stdin, clang-format assumes this</span>
+<span class="go">                              filename to look for a style config file (with</span>
+<span class="go">                              -style=file) and to determine the language.</span>
+<span class="go">  -cursor=<uint>            - The position of the cursor when invoking</span>
+<span class="go">                              clang-format from an editor integration</span>
+<span class="go">  -dump-config              - Dump configuration options to stdout and exit.</span>
+<span class="go">                              Can be used with -style option.</span>
+<span class="go">  -fallback-style=<string>  - The name of the predefined style used as a</span>
+<span class="go">                              fallback in case clang-format is invoked with</span>
+<span class="go">                              -style=file, but can not find the .clang-format</span>
+<span class="go">                              file to use.</span>
+<span class="go">                              Use -fallback-style=none to skip formatting.</span>
+<span class="go">  -i                        - Inplace edit <file>s, if specified.</span>
+<span class="go">  -length=<uint>            - Format a range of this length (in bytes).</span>
+<span class="go">                              Multiple ranges can be formatted by specifying</span>
+<span class="go">                              several -offset and -length pairs.</span>
+<span class="go">                              When only a single -offset is specified without</span>
+<span class="go">                              -length, clang-format will format up to the end</span>
+<span class="go">                              of the file.</span>
+<span class="go">                              Can only be used with one input file.</span>
+<span class="go">  -lines=<string>           - <start line>:<end line> - format a range of</span>
+<span class="go">                              lines (both 1-based).</span>
+<span class="go">                              Multiple ranges can be formatted by specifying</span>
+<span class="go">                              several -lines arguments.</span>
+<span class="go">                              Can't be used with -offset and -length.</span>
+<span class="go">                              Can only be used with one input file.</span>
+<span class="go">  -offset=<uint>            - Format a range starting at this byte offset.</span>
+<span class="go">                              Multiple ranges can be formatted by specifying</span>
+<span class="go">                              several -offset and -length pairs.</span>
+<span class="go">                              Can only be used with one input file.</span>
+<span class="go">  -output-replacements-xml  - Output replacements as XML.</span>
+<span class="go">  -sort-includes            - Sort touched include lines</span>
+<span class="go">  -style=<string>           - Coding style, currently supports:</span>
+<span class="go">                                LLVM, Google, Chromium, Mozilla, WebKit.</span>
+<span class="go">                              Use -style=file to load style configuration from</span>
+<span class="go">                              .clang-format file located in one of the parent</span>
+<span class="go">                              directories of the source file (or current</span>
+<span class="go">                              directory for stdin).</span>
+<span class="go">                              Use -style="{key: value, ...}" to set specific</span>
+<span class="go">                              parameters, e.g.:</span>
+<span class="go">                                -style="{BasedOnStyle: llvm, IndentWidth: 8}"</span>
+
+<span class="go">Generic Options:</span>
+
+<span class="go">  -help                     - Display available options (-help-hidden for more)</span>
+<span class="go">  -help-list                - Display list of available options (-help-list-hidden for more)</span>
+<span class="go">  -version                  - Display the version of this program</span>
+</pre></div>
+</div>
+<p>When the desired code formatting style is different from the available options,
+the style can be customized using the <tt class="docutils literal"><span class="pre">-style="{key:</span> <span class="pre">value,</span> <span class="pre">...}"</span></tt> option or
+by putting your style configuration in the <tt class="docutils literal"><span class="pre">.clang-format</span></tt> or <tt class="docutils literal"><span class="pre">_clang-format</span></tt>
+file in your project’s directory and using <tt class="docutils literal"><span class="pre">clang-format</span> <span class="pre">-style=file</span></tt>.</p>
+<p>An easy way to create the <tt class="docutils literal"><span class="pre">.clang-format</span></tt> file is:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">clang-format -style=llvm -dump-config > .clang-format</span>
+</pre></div>
+</div>
+<p>Available style options are described in <a class="reference internal" href="ClangFormatStyleOptions.html"><em>Clang-Format Style Options</em></a>.</p>
+</div>
+<div class="section" id="vim-integration">
+<h2>Vim Integration<a class="headerlink" href="#vim-integration" title="Permalink to this headline">¶</a></h2>
+<p>There is an integration for <strong class="program">vim</strong> which lets you run the
+<strong class="program">clang-format</strong> standalone tool on your current buffer, optionally
+selecting regions to reformat. The integration has the form of a <cite>python</cite>-file
+which can be found under <cite>clang/tools/clang-format/clang-format.py</cite>.</p>
+<p>This can be integrated by adding the following to your <cite>.vimrc</cite>:</p>
+<div class="highlight-vim"><div class="highlight"><pre>map <span class="p"><</span>C<span class="p">-</span>K<span class="p">></span> :<span class="k">pyf</span> <span class="p"><</span><span class="nb">path</span><span class="p">-</span><span class="k">to</span><span class="p">-</span>this<span class="p">-</span><span class="k">file</span><span class="p">></span>/clang<span class="p">-</span>format.<span class="k">py</span><span class="p"><</span><span class="k">cr</span><span class="p">></span>
+imap <span class="p"><</span>C<span class="p">-</span>K<span class="p">></span> <span class="p"><</span><span class="k">c</span><span class="p">-</span><span class="k">o</span><span class="p">></span>:<span class="k">pyf</span> <span class="p"><</span><span class="nb">path</span><span class="p">-</span><span class="k">to</span><span class="p">-</span>this<span class="p">-</span><span class="k">file</span><span class="p">></span>/clang<span class="p">-</span>format.<span class="k">py</span><span class="p"><</span><span class="k">cr</span><span class="p">></span>
+</pre></div>
+</div>
+<p>The first line enables <strong class="program">clang-format</strong> for NORMAL and VISUAL mode, the
+second line adds support for INSERT mode. Change “C-K” to another binding if
+you need <strong class="program">clang-format</strong> on a different key (C-K stands for Ctrl+k).</p>
+<p>With this integration you can press the bound key and clang-format will
+format the current line in NORMAL and INSERT mode or the selected region in
+VISUAL mode. The line or region is extended to the next bigger syntactic
+entity.</p>
+<p>It operates on the current, potentially unsaved buffer and does not create
+or save any files. To revert a formatting, just undo.</p>
+</div>
+<div class="section" id="emacs-integration">
+<h2>Emacs Integration<a class="headerlink" href="#emacs-integration" title="Permalink to this headline">¶</a></h2>
+<p>Similar to the integration for <strong class="program">vim</strong>, there is an integration for
+<strong class="program">emacs</strong>. It can be found at <cite>clang/tools/clang-format/clang-format.el</cite>
+and used by adding this to your <cite>.emacs</cite>:</p>
+<div class="highlight-common-lisp"><div class="highlight"><pre><span class="p">(</span><span class="nb">load</span> <span class="s">"<path-to-clang>/tools/clang-format/clang-format.el"</span><span class="p">)</span>
+<span class="p">(</span><span class="nv">global-set-key</span> <span class="nv">[C-M-tab]</span> <span class="ss">'clang-format-region</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This binds the function <cite>clang-format-region</cite> to C-M-tab, which then formats the
+current line or selected region.</p>
+</div>
+<div class="section" id="bbedit-integration">
+<h2>BBEdit Integration<a class="headerlink" href="#bbedit-integration" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">clang-format</strong> cannot be used as a text filter with BBEdit, but works
+well via a script. The AppleScript to do this integration can be found at
+<cite>clang/tools/clang-format/clang-format-bbedit.applescript</cite>; place a copy in
+<cite>~/Library/Application Support/BBEdit/Scripts</cite>, and edit the path within it to
+point to your local copy of <strong class="program">clang-format</strong>.</p>
+<p>With this integration you can select the script from the Script menu and
+<strong class="program">clang-format</strong> will format the selection. Note that you can rename the
+menu item by renaming the script, and can assign the menu item a keyboard
+shortcut in the BBEdit preferences, under Menus & Shortcuts.</p>
+</div>
+<div class="section" id="visual-studio-integration">
+<h2>Visual Studio Integration<a class="headerlink" href="#visual-studio-integration" title="Permalink to this headline">¶</a></h2>
+<p>Download the latest Visual Studio extension from the <a class="reference external" href="http://llvm.org/builds/">alpha build site</a>. The default key-binding is Ctrl-R,Ctrl-F.</p>
+</div>
+<div class="section" id="script-for-patch-reformatting">
+<h2>Script for patch reformatting<a class="headerlink" href="#script-for-patch-reformatting" title="Permalink to this headline">¶</a></h2>
+<p>The python script <cite>clang/tools/clang-format-diff.py</cite> parses the output of
+a unified diff and reformats all contained lines with <strong class="program">clang-format</strong>.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE]</span>
+
+<span class="go">Reformat changed lines in diff. Without -i option just output the diff that</span>
+<span class="go">would be introduced.</span>
+
+<span class="go">optional arguments:</span>
+<span class="go">  -h, --help      show this help message and exit</span>
+<span class="go">  -i              apply edits to files instead of displaying a diff</span>
+<span class="go">  -p NUM          strip the smallest prefix containing P slashes</span>
+<span class="go">  -regex PATTERN  custom pattern selecting file paths to reformat</span>
+<span class="go">  -style STYLE    formatting style to apply (LLVM, Google, Chromium, Mozilla,</span>
+<span class="go">                  WebKit)</span>
+</pre></div>
+</div>
+<p>So to reformat all the lines in the latest <strong class="program">git</strong> commit, just do:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1</span>
+</pre></div>
+</div>
+<p>In an SVN client, you can do:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i</span>
+</pre></div>
+</div>
+<p>The option <cite>-U0</cite> will create a diff without context lines (the script would format
+those as well).</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="ClangCheck.html">ClangCheck</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangFormatStyleOptions.html">Clang-Format Style Options</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/ClangFormatStyleOptions.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ClangFormatStyleOptions.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ClangFormatStyleOptions.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ClangFormatStyleOptions.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,767 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Clang-Format Style Options — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="next" title="“Clang” CFE Internals Manual" href="InternalsManual.html" />
+    <link rel="prev" title="ClangFormat" href="ClangFormat.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Clang-Format Style Options</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="ClangFormat.html">ClangFormat</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="InternalsManual.html">“Clang” CFE Internals Manual</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clang-format-style-options">
+<h1>Clang-Format Style Options<a class="headerlink" href="#clang-format-style-options" title="Permalink to this headline">¶</a></h1>
+<p><a class="reference internal" href=""><em>Clang-Format Style Options</em></a> describes configurable formatting style options
+supported by <a class="reference internal" href="LibFormat.html"><em>LibFormat</em></a> and <a class="reference internal" href="ClangFormat.html"><em>ClangFormat</em></a>.</p>
+<p>When using <strong class="program">clang-format</strong> command line utility or
+<tt class="docutils literal"><span class="pre">clang::format::reformat(...)</span></tt> functions from code, one can either use one of
+the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit) or create a
+custom style by configuring specific style options.</p>
+<div class="section" id="configuring-style-with-clang-format">
+<h2>Configuring Style with clang-format<a class="headerlink" href="#configuring-style-with-clang-format" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">clang-format</strong> supports two ways to provide custom style options:
+directly specify style configuration in the <tt class="docutils literal"><span class="pre">-style=</span></tt> command line option or
+use <tt class="docutils literal"><span class="pre">-style=file</span></tt> and put style configuration in the <tt class="docutils literal"><span class="pre">.clang-format</span></tt> or
+<tt class="docutils literal"><span class="pre">_clang-format</span></tt> file in the project directory.</p>
+<p>When using <tt class="docutils literal"><span class="pre">-style=file</span></tt>, <strong class="program">clang-format</strong> for each input file will
+try to find the <tt class="docutils literal"><span class="pre">.clang-format</span></tt> file located in the closest parent directory
+of the input file. When the standard input is used, the search is started from
+the current directory.</p>
+<p>The <tt class="docutils literal"><span class="pre">.clang-format</span></tt> file uses YAML format:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">key1</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">value1</span>
+<span class="l-Scalar-Plain">key2</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">value2</span>
+<span class="c1"># A comment.</span>
+<span class="nn">...</span>
+</pre></div>
+</div>
+<p>The configuration file can consist of several sections each having different
+<tt class="docutils literal"><span class="pre">Language:</span></tt> parameter denoting the programming language this section of the
+configuration is targeted at. See the description of the <strong>Language</strong> option
+below for the list of supported languages. The first section may have no
+language set, it will set the default style options for all lanugages.
+Configuration sections for specific language will override options set in the
+default section.</p>
+<p>When <strong class="program">clang-format</strong> formats a file, it auto-detects the language using
+the file name. When formatting standard input or a file that doesn’t have the
+extension corresponding to its language, <tt class="docutils literal"><span class="pre">-assume-filename=</span></tt> option can be
+used to override the file name <strong class="program">clang-format</strong> uses to detect the
+language.</p>
+<p>An example of a configuration file for multiple languages:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="nn">---</span>
+<span class="c1"># We'll use defaults from the LLVM style, but with 4 columns indentation.</span>
+<span class="l-Scalar-Plain">BasedOnStyle</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">LLVM</span>
+<span class="l-Scalar-Plain">IndentWidth</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">4</span>
+<span class="nn">---</span>
+<span class="l-Scalar-Plain">Language</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Cpp</span>
+<span class="c1"># Force pointers to the type for C++.</span>
+<span class="l-Scalar-Plain">DerivePointerAlignment</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
+<span class="l-Scalar-Plain">PointerAlignment</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Left</span>
+<span class="nn">---</span>
+<span class="l-Scalar-Plain">Language</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">JavaScript</span>
+<span class="c1"># Use 100 columns for JS.</span>
+<span class="l-Scalar-Plain">ColumnLimit</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">100</span>
+<span class="nn">---</span>
+<span class="l-Scalar-Plain">Language</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Proto</span>
+<span class="c1"># Don't format .proto files.</span>
+<span class="l-Scalar-Plain">DisableFormat</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">true</span>
+<span class="nn">...</span>
+</pre></div>
+</div>
+<p>An easy way to get a valid <tt class="docutils literal"><span class="pre">.clang-format</span></tt> file containing all configuration
+options of a certain predefined style is:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">clang-format -style=llvm -dump-config > .clang-format</span>
+</pre></div>
+</div>
+<p>When specifying configuration in the <tt class="docutils literal"><span class="pre">-style=</span></tt> option, the same configuration
+is applied for all input files. The format of the configuration is:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">-style='{key1: value1, key2: value2, ...}'</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="disabling-formatting-on-a-piece-of-code">
+<h2>Disabling Formatting on a Piece of Code<a class="headerlink" href="#disabling-formatting-on-a-piece-of-code" title="Permalink to this headline">¶</a></h2>
+<p>Clang-format understands also special comments that switch formatting in a
+delimited range. The code between a comment <tt class="docutils literal"><span class="pre">//</span> <span class="pre">clang-format</span> <span class="pre">off</span></tt> or
+<tt class="docutils literal"><span class="pre">/*</span> <span class="pre">clang-format</span> <span class="pre">off</span> <span class="pre">*/</span></tt> up to a comment <tt class="docutils literal"><span class="pre">//</span> <span class="pre">clang-format</span> <span class="pre">on</span></tt> or
+<tt class="docutils literal"><span class="pre">/*</span> <span class="pre">clang-format</span> <span class="pre">on</span> <span class="pre">*/</span></tt> will not be formatted. The comments themselves
+will be formatted (aligned) normally.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">formatted_code</span><span class="p">;</span>
+<span class="c1">// clang-format off</span>
+    <span class="kt">void</span>    <span class="n">unformatted_code</span>  <span class="p">;</span>
+<span class="c1">// clang-format on</span>
+<span class="kt">void</span> <span class="n">formatted_code_again</span><span class="p">;</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="configuring-style-in-code">
+<h2>Configuring Style in Code<a class="headerlink" href="#configuring-style-in-code" title="Permalink to this headline">¶</a></h2>
+<p>When using <tt class="docutils literal"><span class="pre">clang::format::reformat(...)</span></tt> functions, the format is specified
+by supplying the <a class="reference external" href="http://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html">clang::format::FormatStyle</a>
+structure.</p>
+</div>
+<div class="section" id="configurable-format-style-options">
+<h2>Configurable Format Style Options<a class="headerlink" href="#configurable-format-style-options" title="Permalink to this headline">¶</a></h2>
+<p>This section lists the supported style options. Value type is specified for
+each option. For enumeration types possible values are specified both as a C++
+enumeration member (with a prefix, e.g. <tt class="docutils literal"><span class="pre">LS_Auto</span></tt>), and as a value usable in
+the configuration (without a prefix: <tt class="docutils literal"><span class="pre">Auto</span></tt>).</p>
+<dl class="docutils">
+<dt><strong>BasedOnStyle</strong> (<tt class="docutils literal"><span class="pre">string</span></tt>)</dt>
+<dd><p class="first">The style used for all options not specifically set in the configuration.</p>
+<p>This option is supported only in the <strong class="program">clang-format</strong> configuration
+(both within <tt class="docutils literal"><span class="pre">-style='{...}'</span></tt> and the <tt class="docutils literal"><span class="pre">.clang-format</span></tt> file).</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">LLVM</span></tt>
+A style complying with the <a class="reference external" href="http://llvm.org/docs/CodingStandards.html">LLVM coding standards</a></li>
+<li><tt class="docutils literal"><span class="pre">Google</span></tt>
+A style complying with <a class="reference external" href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml">Google’s C++ style guide</a></li>
+<li><tt class="docutils literal"><span class="pre">Chromium</span></tt>
+A style complying with <a class="reference external" href="http://www.chromium.org/developers/coding-style">Chromium’s style guide</a></li>
+<li><tt class="docutils literal"><span class="pre">Mozilla</span></tt>
+A style complying with <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style">Mozilla’s style guide</a></li>
+<li><tt class="docutils literal"><span class="pre">WebKit</span></tt>
+A style complying with <a class="reference external" href="http://www.webkit.org/coding/coding-style.html">WebKit’s style guide</a></li>
+</ul>
+</dd>
+</dl>
+<dl class="docutils">
+<dt><strong>AccessModifierOffset</strong> (<tt class="docutils literal"><span class="pre">int</span></tt>)</dt>
+<dd>The extra indent or outdent of access modifiers, e.g. <tt class="docutils literal"><span class="pre">public:</span></tt>.</dd>
+<dt><strong>AlignAfterOpenBracket</strong> (<tt class="docutils literal"><span class="pre">BracketAlignmentStyle</span></tt>)</dt>
+<dd><p class="first">If <tt class="docutils literal"><span class="pre">true</span></tt>, horizontally aligns arguments after an open bracket.</p>
+<p>This applies to round brackets (parentheses), angle brackets and square
+brackets.</p>
+<p>Possible values:</p>
+<ul class="last">
+<li><p class="first"><tt class="docutils literal"><span class="pre">BAS_Align</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Align</span></tt>)
+Align parameters on the open bracket, e.g.:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">someLongFunction</span><span class="p">(</span><span class="n">argument1</span><span class="p">,</span>
+                 <span class="n">argument2</span><span class="p">);</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">BAS_DontAlign</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">DontAlign</span></tt>)
+Don’t align, instead use <tt class="docutils literal"><span class="pre">ContinuationIndentWidth</span></tt>, e.g.:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">someLongFunction</span><span class="p">(</span><span class="n">argument1</span><span class="p">,</span>
+    <span class="n">argument2</span><span class="p">);</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">BAS_AlwaysBreak</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">AlwaysBreak</span></tt>)
+Always break after an open bracket, if the parameters don’t fit
+on a single line, e.g.:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">someLongFunction</span><span class="p">(</span>
+    <span class="n">argument1</span><span class="p">,</span> <span class="n">argument2</span><span class="p">);</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</dd>
+<dt><strong>AlignConsecutiveAssignments</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">If <tt class="docutils literal"><span class="pre">true</span></tt>, aligns consecutive assignments.</p>
+<p>This will align the assignment operators of consecutive lines. This
+will result in formattings like</p>
+<div class="last highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">aaaa</span> <span class="o">=</span> <span class="mi">12</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">b</span>    <span class="o">=</span> <span class="mi">23</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">ccc</span>  <span class="o">=</span> <span class="mi">23</span><span class="p">;</span>
+</pre></div>
+</div>
+</dd>
+<dt><strong>AlignConsecutiveDeclarations</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">If <tt class="docutils literal"><span class="pre">true</span></tt>, aligns consecutive declarations.</p>
+<p>This will align the declaration names of consecutive lines. This
+will result in formattings like</p>
+<div class="last highlight-c++"><div class="highlight"><pre><span class="kt">int</span>         <span class="n">aaaa</span> <span class="o">=</span> <span class="mi">12</span><span class="p">;</span>
+<span class="kt">float</span>       <span class="n">b</span> <span class="o">=</span> <span class="mi">23</span><span class="p">;</span>
+<span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">ccc</span> <span class="o">=</span> <span class="mi">23</span><span class="p">;</span>
+</pre></div>
+</div>
+</dd>
+<dt><strong>AlignEscapedNewlinesLeft</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, aligns escaped newlines as far left as possible.
+Otherwise puts them into the right-most column.</dd>
+<dt><strong>AlignOperands</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">If <tt class="docutils literal"><span class="pre">true</span></tt>, horizontally align operands of binary and ternary
+expressions.</p>
+<p>Specifically, this aligns operands of a single expression that needs to be
+split over multiple lines, e.g.:</p>
+<div class="last highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">aaa</span> <span class="o">=</span> <span class="n">bbbbbbbbbbbbbbb</span> <span class="o">+</span>
+          <span class="n">ccccccccccccccc</span><span class="p">;</span>
+</pre></div>
+</div>
+</dd>
+<dt><strong>AlignTrailingComments</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, aligns trailing comments.</dd>
+<dt><strong>AllowAllParametersOfDeclarationOnNextLine</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Allow putting all parameters of a function declaration onto
+the next line even if <tt class="docutils literal"><span class="pre">BinPackParameters</span></tt> is <tt class="docutils literal"><span class="pre">false</span></tt>.</dd>
+<dt><strong>AllowShortBlocksOnASingleLine</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">Allows contracting simple braced statements to a single line.</p>
+<p class="last">E.g., this allows <tt class="docutils literal"><span class="pre">if</span> <span class="pre">(a)</span> <span class="pre">{</span> <span class="pre">return;</span> <span class="pre">}</span></tt> to be put on a single line.</p>
+</dd>
+<dt><strong>AllowShortCaseLabelsOnASingleLine</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, short case labels will be contracted to a single line.</dd>
+<dt><strong>AllowShortFunctionsOnASingleLine</strong> (<tt class="docutils literal"><span class="pre">ShortFunctionStyle</span></tt>)</dt>
+<dd><p class="first">Dependent on the value, <tt class="docutils literal"><span class="pre">int</span> <span class="pre">f()</span> <span class="pre">{</span> <span class="pre">return</span> <span class="pre">0;</span> <span class="pre">}</span></tt> can be put on a
+single line.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">SFS_None</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">None</span></tt>)
+Never merge functions into a single line.</li>
+<li><tt class="docutils literal"><span class="pre">SFS_Empty</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Empty</span></tt>)
+Only merge empty functions.</li>
+<li><tt class="docutils literal"><span class="pre">SFS_Inline</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Inline</span></tt>)
+Only merge functions defined inside a class. Implies “empty”.</li>
+<li><tt class="docutils literal"><span class="pre">SFS_All</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">All</span></tt>)
+Merge all functions fitting on a single line.</li>
+</ul>
+</dd>
+<dt><strong>AllowShortIfStatementsOnASingleLine</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, <tt class="docutils literal"><span class="pre">if</span> <span class="pre">(a)</span> <span class="pre">return;</span></tt> can be put on a single line.</dd>
+<dt><strong>AllowShortLoopsOnASingleLine</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, <tt class="docutils literal"><span class="pre">while</span> <span class="pre">(true)</span> <span class="pre">continue;</span></tt> can be put on a single
+line.</dd>
+<dt><strong>AlwaysBreakAfterDefinitionReturnType</strong> (<tt class="docutils literal"><span class="pre">DefinitionReturnTypeBreakingStyle</span></tt>)</dt>
+<dd><p class="first">The function definition return type breaking style to use.  This
+option is deprecated and is retained for backwards compatibility.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">DRTBS_None</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">None</span></tt>)
+Break after return type automatically.
+<tt class="docutils literal"><span class="pre">PenaltyReturnTypeOnItsOwnLine</span></tt> is taken into account.</li>
+<li><tt class="docutils literal"><span class="pre">DRTBS_All</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">All</span></tt>)
+Always break after the return type.</li>
+<li><tt class="docutils literal"><span class="pre">DRTBS_TopLevel</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">TopLevel</span></tt>)
+Always break after the return types of top-level functions.</li>
+</ul>
+</dd>
+<dt><strong>AlwaysBreakAfterReturnType</strong> (<tt class="docutils literal"><span class="pre">ReturnTypeBreakingStyle</span></tt>)</dt>
+<dd><p class="first">The function declaration return type breaking style to use.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">RTBS_None</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">None</span></tt>)
+Break after return type automatically.
+<tt class="docutils literal"><span class="pre">PenaltyReturnTypeOnItsOwnLine</span></tt> is taken into account.</li>
+<li><tt class="docutils literal"><span class="pre">RTBS_All</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">All</span></tt>)
+Always break after the return type.</li>
+<li><tt class="docutils literal"><span class="pre">RTBS_TopLevel</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">TopLevel</span></tt>)
+Always break after the return types of top-level functions.</li>
+<li><tt class="docutils literal"><span class="pre">RTBS_AllDefinitions</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">AllDefinitions</span></tt>)
+Always break after the return type of function definitions.</li>
+<li><tt class="docutils literal"><span class="pre">RTBS_TopLevelDefinitions</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">TopLevelDefinitions</span></tt>)
+Always break after the return type of top-level definitions.</li>
+</ul>
+</dd>
+<dt><strong>AlwaysBreakBeforeMultilineStrings</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">If <tt class="docutils literal"><span class="pre">true</span></tt>, always break before multiline string literals.</p>
+<p class="last">This flag is mean to make cases where there are multiple multiline strings
+in a file look more consistent. Thus, it will only take effect if wrapping
+the string at that point leads to it being indented
+<tt class="docutils literal"><span class="pre">ContinuationIndentWidth</span></tt> spaces from the start of the line.</p>
+</dd>
+<dt><strong>AlwaysBreakTemplateDeclarations</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, always break after the <tt class="docutils literal"><span class="pre">template<...></span></tt> of a template
+declaration.</dd>
+<dt><strong>BinPackArguments</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">false</span></tt>, a function call’s arguments will either be all on the
+same line or will have one line each.</dd>
+<dt><strong>BinPackParameters</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">false</span></tt>, a function declaration’s or function definition’s
+parameters will either all be on the same line or will have one line each.</dd>
+<dt><strong>BraceWrapping</strong> (<tt class="docutils literal"><span class="pre">BraceWrappingFlags</span></tt>)</dt>
+<dd><p class="first">Control of individual brace wrapping cases.</p>
+<p>If <tt class="docutils literal"><span class="pre">BreakBeforeBraces</span></tt> is set to <tt class="docutils literal"><span class="pre">BS_Custom</span></tt>, use this to specify how
+each individual brace case should be handled. Otherwise, this is ignored.</p>
+<p>Nested configuration flags:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">AfterClass</span></tt> Wrap class definitions.</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">AfterControlStatement</span></tt> Wrap control statements (<tt class="docutils literal"><span class="pre">if</span></tt>/<tt class="docutils literal"><span class="pre">for</span></tt>/<tt class="docutils literal"><span class="pre">while</span></tt>/<tt class="docutils literal"><span class="pre">switch</span></tt>/..).</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">AfterEnum</span></tt> Wrap enum definitions.</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">AfterFunction</span></tt> Wrap function definitions.</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">AfterNamespace</span></tt> Wrap namespace definitions.</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">AfterObjCDeclaration</span></tt> Wrap ObjC definitions (<tt class="docutils literal"><span class="pre">@autoreleasepool</span></tt>, interfaces, ..).</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">AfterStruct</span></tt> Wrap struct definitions.</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">AfterUnion</span></tt> Wrap union definitions.</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">BeforeCatch</span></tt> Wrap before <tt class="docutils literal"><span class="pre">catch</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">BeforeElse</span></tt> Wrap before <tt class="docutils literal"><span class="pre">else</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">IndentBraces</span></tt> Indent the wrapped braces themselves.</li>
+</ul>
+</dd>
+<dt><strong>BreakAfterJavaFieldAnnotations</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Break after each annotation on a field in Java files.</dd>
+<dt><strong>BreakBeforeBinaryOperators</strong> (<tt class="docutils literal"><span class="pre">BinaryOperatorStyle</span></tt>)</dt>
+<dd><p class="first">The way to wrap binary operators.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">BOS_None</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">None</span></tt>)
+Break after operators.</li>
+<li><tt class="docutils literal"><span class="pre">BOS_NonAssignment</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">NonAssignment</span></tt>)
+Break before operators that aren’t assignments.</li>
+<li><tt class="docutils literal"><span class="pre">BOS_All</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">All</span></tt>)
+Break before operators.</li>
+</ul>
+</dd>
+<dt><strong>BreakBeforeBraces</strong> (<tt class="docutils literal"><span class="pre">BraceBreakingStyle</span></tt>)</dt>
+<dd><p class="first">The brace breaking style to use.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">BS_Attach</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Attach</span></tt>)
+Always attach braces to surrounding context.</li>
+<li><tt class="docutils literal"><span class="pre">BS_Linux</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Linux</span></tt>)
+Like <tt class="docutils literal"><span class="pre">Attach</span></tt>, but break before braces on function, namespace and
+class definitions.</li>
+<li><tt class="docutils literal"><span class="pre">BS_Mozilla</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Mozilla</span></tt>)
+Like <tt class="docutils literal"><span class="pre">Attach</span></tt>, but break before braces on enum, function, and record
+definitions.</li>
+<li><tt class="docutils literal"><span class="pre">BS_Stroustrup</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Stroustrup</span></tt>)
+Like <tt class="docutils literal"><span class="pre">Attach</span></tt>, but break before function definitions, <tt class="docutils literal"><span class="pre">catch</span></tt>, and
+<tt class="docutils literal"><span class="pre">else</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">BS_Allman</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Allman</span></tt>)
+Always break before braces.</li>
+<li><tt class="docutils literal"><span class="pre">BS_GNU</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">GNU</span></tt>)
+Always break before braces and add an extra level of indentation to
+braces of control statements, not to those of class, function
+or other definitions.</li>
+<li><tt class="docutils literal"><span class="pre">BS_WebKit</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">WebKit</span></tt>)
+Like <tt class="docutils literal"><span class="pre">Attach</span></tt>, but break before functions.</li>
+<li><tt class="docutils literal"><span class="pre">BS_Custom</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Custom</span></tt>)
+Configure each individual brace in <cite>BraceWrapping</cite>.</li>
+</ul>
+</dd>
+<dt><strong>BreakBeforeTernaryOperators</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, ternary operators will be placed after line breaks.</dd>
+<dt><strong>BreakConstructorInitializersBeforeComma</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Always break constructor initializers before commas and align
+the commas with the colon.</dd>
+<dt><strong>BreakStringLiterals</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Allow breaking string literals when formatting.</dd>
+<dt><strong>ColumnLimit</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd><p class="first">The column limit.</p>
+<p class="last">A column limit of <tt class="docutils literal"><span class="pre">0</span></tt> means that there is no column limit. In this case,
+clang-format will respect the input’s line breaking decisions within
+statements unless they contradict other rules.</p>
+</dd>
+<dt><strong>CommentPragmas</strong> (<tt class="docutils literal"><span class="pre">std::string</span></tt>)</dt>
+<dd>A regular expression that describes comments with special meaning,
+which should not be split into lines or otherwise changed.</dd>
+<dt><strong>ConstructorInitializerAllOnOneLineOrOnePerLine</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If the constructor initializers don’t fit on a line, put each
+initializer on its own line.</dd>
+<dt><strong>ConstructorInitializerIndentWidth</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The number of characters to use for indentation of constructor
+initializer lists.</dd>
+<dt><strong>ContinuationIndentWidth</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>Indent width for line continuations.</dd>
+<dt><strong>Cpp11BracedListStyle</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">If <tt class="docutils literal"><span class="pre">true</span></tt>, format braced lists as best suited for C++11 braced
+lists.</p>
+<p>Important differences:
+- No spaces inside the braced list.
+- No line break before the closing brace.
+- Indentation with the continuation indent, not with the block indent.</p>
+<p class="last">Fundamentally, C++11 braced lists are formatted exactly like function
+calls would be formatted in their place. If the braced list follows a name
+(e.g. a type or variable name), clang-format formats as if the <tt class="docutils literal"><span class="pre">{}</span></tt> were
+the parentheses of a function call with that name. If there is no name,
+a zero-length name is assumed.</p>
+</dd>
+<dt><strong>DerivePointerAlignment</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, analyze the formatted file for the most common
+alignment of <tt class="docutils literal"><span class="pre">&</span></tt> and <tt class="docutils literal"><span class="pre">\*</span></tt>. <tt class="docutils literal"><span class="pre">PointerAlignment</span></tt> is then used only as
+fallback.</dd>
+<dt><strong>DisableFormat</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Disables formatting completely.</dd>
+<dt><strong>ExperimentalAutoDetectBinPacking</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">If <tt class="docutils literal"><span class="pre">true</span></tt>, clang-format detects whether function calls and
+definitions are formatted with one parameter per line.</p>
+<p>Each call can be bin-packed, one-per-line or inconclusive. If it is
+inconclusive, e.g. completely on one line, but a decision needs to be
+made, clang-format analyzes whether there are other bin-packed cases in
+the input file and act accordingly.</p>
+<p class="last">NOTE: This is an experimental flag, that might go away or be renamed. Do
+not use this in config files, etc. Use at your own risk.</p>
+</dd>
+<dt><strong>ForEachMacros</strong> (<tt class="docutils literal"><span class="pre">std::vector<std::string></span></tt>)</dt>
+<dd><p class="first">A vector of macros that should be interpreted as foreach loops
+instead of as function calls.</p>
+<p>These are expected to be macros of the form:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">FOREACH</span><span class="p">(</span><span class="o"><</span><span class="n">variable</span><span class="o">-</span><span class="n">declaration</span><span class="o">></span><span class="p">,</span> <span class="p">...)</span>
+  <span class="o"><</span><span class="n">loop</span><span class="o">-</span><span class="n">body</span><span class="o">></span>
+</pre></div>
+</div>
+<p>In the .clang-format configuration file, this can be configured like:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">ForEachMacros</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span><span class="s">'RANGES_FOR'</span><span class="p-Indicator">,</span> <span class="s">'FOREACH'</span><span class="p-Indicator">]</span>
+</pre></div>
+</div>
+<p class="last">For example: BOOST_FOREACH.</p>
+</dd>
+<dt><strong>IncludeCategories</strong> (<tt class="docutils literal"><span class="pre">std::vector<IncludeCategory></span></tt>)</dt>
+<dd><p class="first">Regular expressions denoting the different <tt class="docutils literal"><span class="pre">#include</span></tt> categories
+used for ordering <tt class="docutils literal"><span class="pre">#includes</span></tt>.</p>
+<p>These regular expressions are matched against the filename of an include
+(including the <> or “”) in order. The value belonging to the first
+matching regular expression is assigned and <tt class="docutils literal"><span class="pre">#includes</span></tt> are sorted first
+according to increasing category number and then alphabetically within
+each category.</p>
+<p>If none of the regular expressions match, INT_MAX is assigned as
+category. The main header for a source file automatically gets category 0.
+so that it is generally kept at the beginning of the <tt class="docutils literal"><span class="pre">#includes</span></tt>
+(<a class="reference external" href="http://llvm.org/docs/CodingStandards.html#include-style">http://llvm.org/docs/CodingStandards.html#include-style</a>). However, you
+can also assign negative priorities if you have certain headers that
+always need to be first.</p>
+<p>To configure this in the .clang-format file, use:</p>
+<div class="last highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">IncludeCategories</span><span class="p-Indicator">:</span>
+  <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Regex</span><span class="p-Indicator">:</span>           <span class="s">'^"(llvm|llvm-c|clang|clang-c)/'</span>
+    <span class="l-Scalar-Plain">Priority</span><span class="p-Indicator">:</span>        <span class="l-Scalar-Plain">2</span>
+  <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Regex</span><span class="p-Indicator">:</span>           <span class="s">'^(<|"(gtest|isl|json)/)'</span>
+    <span class="l-Scalar-Plain">Priority</span><span class="p-Indicator">:</span>        <span class="l-Scalar-Plain">3</span>
+  <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">Regex</span><span class="p-Indicator">:</span>           <span class="s">'.\*'</span>
+    <span class="l-Scalar-Plain">Priority</span><span class="p-Indicator">:</span>        <span class="l-Scalar-Plain">1</span>
+</pre></div>
+</div>
+</dd>
+<dt><strong>IncludeIsMainRegex</strong> (<tt class="docutils literal"><span class="pre">std::string</span></tt>)</dt>
+<dd><p class="first">Specify a regular expression of suffixes that are allowed in the
+file-to-main-include mapping.</p>
+<p>When guessing whether a #include is the “main” include (to assign
+category 0, see above), use this regex of allowed suffixes to the header
+stem. A partial match is done, so that:
+- “” means “arbitrary suffix”
+- “$” means “no suffix”</p>
+<p class="last">For example, if configured to “(_test)?$”, then a header a.h would be seen
+as the “main” include in both a.cc and a_test.cc.</p>
+</dd>
+<dt><strong>IndentCaseLabels</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd><p class="first">Indent case labels one level from the switch statement.</p>
+<p class="last">When <tt class="docutils literal"><span class="pre">false</span></tt>, use the same indentation level as for the switch statement.
+Switch statement body is always indented one level more than case labels.</p>
+</dd>
+<dt><strong>IndentWidth</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The number of columns to use for indentation.</dd>
+<dt><strong>IndentWrappedFunctionNames</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Indent if a function definition or declaration is wrapped after the
+type.</dd>
+<dt><strong>JavaScriptQuotes</strong> (<tt class="docutils literal"><span class="pre">JavaScriptQuoteStyle</span></tt>)</dt>
+<dd><p class="first">The JavaScriptQuoteStyle to use for JavaScript strings.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">JSQS_Leave</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Leave</span></tt>)
+Leave string quotes as they are.</li>
+<li><tt class="docutils literal"><span class="pre">JSQS_Single</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Single</span></tt>)
+Always use single quotes.</li>
+<li><tt class="docutils literal"><span class="pre">JSQS_Double</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Double</span></tt>)
+Always use double quotes.</li>
+</ul>
+</dd>
+<dt><strong>KeepEmptyLinesAtTheStartOfBlocks</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If true, empty lines at the start of blocks are kept.</dd>
+<dt><strong>Language</strong> (<tt class="docutils literal"><span class="pre">LanguageKind</span></tt>)</dt>
+<dd><p class="first">Language, this format style is targeted at.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">LK_None</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">None</span></tt>)
+Do not use.</li>
+<li><tt class="docutils literal"><span class="pre">LK_Cpp</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Cpp</span></tt>)
+Should be used for C, C++, ObjectiveC, ObjectiveC++.</li>
+<li><tt class="docutils literal"><span class="pre">LK_Java</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Java</span></tt>)
+Should be used for Java.</li>
+<li><tt class="docutils literal"><span class="pre">LK_JavaScript</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">JavaScript</span></tt>)
+Should be used for JavaScript.</li>
+<li><tt class="docutils literal"><span class="pre">LK_Proto</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Proto</span></tt>)
+Should be used for Protocol Buffers
+(<a class="reference external" href="https://developers.google.com/protocol-buffers/">https://developers.google.com/protocol-buffers/</a>).</li>
+<li><tt class="docutils literal"><span class="pre">LK_TableGen</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">TableGen</span></tt>)
+Should be used for TableGen code.</li>
+</ul>
+</dd>
+<dt><strong>MacroBlockBegin</strong> (<tt class="docutils literal"><span class="pre">std::string</span></tt>)</dt>
+<dd>A regular expression matching macros that start a block.</dd>
+<dt><strong>MacroBlockEnd</strong> (<tt class="docutils literal"><span class="pre">std::string</span></tt>)</dt>
+<dd>A regular expression matching macros that end a block.</dd>
+<dt><strong>MaxEmptyLinesToKeep</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The maximum number of consecutive empty lines to keep.</dd>
+<dt><strong>NamespaceIndentation</strong> (<tt class="docutils literal"><span class="pre">NamespaceIndentationKind</span></tt>)</dt>
+<dd><p class="first">The indentation used for namespaces.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">NI_None</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">None</span></tt>)
+Don’t indent in namespaces.</li>
+<li><tt class="docutils literal"><span class="pre">NI_Inner</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Inner</span></tt>)
+Indent only in inner namespaces (nested in other namespaces).</li>
+<li><tt class="docutils literal"><span class="pre">NI_All</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">All</span></tt>)
+Indent in all namespaces.</li>
+</ul>
+</dd>
+<dt><strong>ObjCBlockIndentWidth</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The number of characters to use for indentation of ObjC blocks.</dd>
+<dt><strong>ObjCSpaceAfterProperty</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Add a space after <tt class="docutils literal"><span class="pre">@property</span></tt> in Objective-C, i.e. use
+<tt class="docutils literal"><span class="pre">@property</span> <span class="pre">(readonly)</span></tt> instead of <tt class="docutils literal"><span class="pre">@property(readonly)</span></tt>.</dd>
+<dt><strong>ObjCSpaceBeforeProtocolList</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>Add a space in front of an Objective-C protocol list, i.e. use
+<tt class="docutils literal"><span class="pre">Foo</span> <span class="pre"><Protocol></span></tt> instead of <tt class="docutils literal"><span class="pre">Foo<Protocol></span></tt>.</dd>
+<dt><strong>PenaltyBreakBeforeFirstCallParameter</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The penalty for breaking a function call after <tt class="docutils literal"><span class="pre">call(</span></tt>.</dd>
+<dt><strong>PenaltyBreakComment</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The penalty for each line break introduced inside a comment.</dd>
+<dt><strong>PenaltyBreakFirstLessLess</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The penalty for breaking before the first <tt class="docutils literal"><span class="pre"><<</span></tt>.</dd>
+<dt><strong>PenaltyBreakString</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The penalty for each line break introduced inside a string literal.</dd>
+<dt><strong>PenaltyExcessCharacter</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The penalty for each character outside of the column limit.</dd>
+<dt><strong>PenaltyReturnTypeOnItsOwnLine</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>Penalty for putting the return type of a function onto its own
+line.</dd>
+<dt><strong>PointerAlignment</strong> (<tt class="docutils literal"><span class="pre">PointerAlignmentStyle</span></tt>)</dt>
+<dd><p class="first">Pointer and reference alignment style.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">PAS_Left</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Left</span></tt>)
+Align pointer to the left.</li>
+<li><tt class="docutils literal"><span class="pre">PAS_Right</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Right</span></tt>)
+Align pointer to the right.</li>
+<li><tt class="docutils literal"><span class="pre">PAS_Middle</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Middle</span></tt>)
+Align pointer in the middle.</li>
+</ul>
+</dd>
+<dt><strong>ReflowComments</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, clang-format will attempt to re-flow comments.</dd>
+<dt><strong>SortIncludes</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, clang-format will sort <tt class="docutils literal"><span class="pre">#includes</span></tt>.</dd>
+<dt><strong>SpaceAfterCStyleCast</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, a space may be inserted after C style casts.</dd>
+<dt><strong>SpaceAfterTemplateKeyword</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, a space will be inserted after the ‘template’ keyword.</dd>
+<dt><strong>SpaceBeforeAssignmentOperators</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">false</span></tt>, spaces will be removed before assignment operators.</dd>
+<dt><strong>SpaceBeforeParens</strong> (<tt class="docutils literal"><span class="pre">SpaceBeforeParensOptions</span></tt>)</dt>
+<dd><p class="first">Defines in which cases to put a space before opening parentheses.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">SBPO_Never</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Never</span></tt>)
+Never put a space before opening parentheses.</li>
+<li><tt class="docutils literal"><span class="pre">SBPO_ControlStatements</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">ControlStatements</span></tt>)
+Put a space before opening parentheses only after control statement
+keywords (<tt class="docutils literal"><span class="pre">for/if/while...</span></tt>).</li>
+<li><tt class="docutils literal"><span class="pre">SBPO_Always</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Always</span></tt>)
+Always put a space before opening parentheses, except when it’s
+prohibited by the syntax rules (in function-like macro definitions) or
+when determined by other style rules (after unary operators, opening
+parentheses, etc.)</li>
+</ul>
+</dd>
+<dt><strong>SpaceInEmptyParentheses</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, spaces may be inserted into <tt class="docutils literal"><span class="pre">()</span></tt>.</dd>
+<dt><strong>SpacesBeforeTrailingComments</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd><p class="first">The number of spaces before trailing line comments
+(<tt class="docutils literal"><span class="pre">//</span></tt> - comments).</p>
+<p class="last">This does not affect trailing block comments (<tt class="docutils literal"><span class="pre">/*</span></tt> - comments) as
+those commonly have different usage patterns and a number of special
+cases.</p>
+</dd>
+<dt><strong>SpacesInAngles</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, spaces will be inserted after <tt class="docutils literal"><span class="pre"><</span></tt> and before <tt class="docutils literal"><span class="pre">></span></tt>
+in template argument lists.</dd>
+<dt><strong>SpacesInCStyleCastParentheses</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, spaces may be inserted into C style casts.</dd>
+<dt><strong>SpacesInContainerLiterals</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, spaces are inserted inside container literals (e.g.
+ObjC and Javascript array and dict literals).</dd>
+<dt><strong>SpacesInParentheses</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, spaces will be inserted after <tt class="docutils literal"><span class="pre">(</span></tt> and before <tt class="docutils literal"><span class="pre">)</span></tt>.</dd>
+<dt><strong>SpacesInSquareBrackets</strong> (<tt class="docutils literal"><span class="pre">bool</span></tt>)</dt>
+<dd>If <tt class="docutils literal"><span class="pre">true</span></tt>, spaces will be inserted after <tt class="docutils literal"><span class="pre">[</span></tt> and before <tt class="docutils literal"><span class="pre">]</span></tt>.</dd>
+<dt><strong>Standard</strong> (<tt class="docutils literal"><span class="pre">LanguageStandard</span></tt>)</dt>
+<dd><p class="first">Format compatible with this standard, e.g. use <tt class="docutils literal"><span class="pre">A<A<int></span> <span class="pre">></span></tt>
+instead of <tt class="docutils literal"><span class="pre">A<A<int>></span></tt> for <tt class="docutils literal"><span class="pre">LS_Cpp03</span></tt>.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">LS_Cpp03</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Cpp03</span></tt>)
+Use C++03-compatible syntax.</li>
+<li><tt class="docutils literal"><span class="pre">LS_Cpp11</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Cpp11</span></tt>)
+Use features of C++11 (e.g. <tt class="docutils literal"><span class="pre">A<A<int>></span></tt> instead of <tt class="docutils literal"><span class="pre">A<A<int></span> <span class="pre">></span></tt>).</li>
+<li><tt class="docutils literal"><span class="pre">LS_Auto</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Auto</span></tt>)
+Automatic detection based on the input.</li>
+</ul>
+</dd>
+<dt><strong>TabWidth</strong> (<tt class="docutils literal"><span class="pre">unsigned</span></tt>)</dt>
+<dd>The number of columns used for tab stops.</dd>
+<dt><strong>UseTab</strong> (<tt class="docutils literal"><span class="pre">UseTabStyle</span></tt>)</dt>
+<dd><p class="first">The way to use tab characters in the resulting file.</p>
+<p>Possible values:</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">UT_Never</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Never</span></tt>)
+Never use tab.</li>
+<li><tt class="docutils literal"><span class="pre">UT_ForIndentation</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">ForIndentation</span></tt>)
+Use tabs only for indentation.</li>
+<li><tt class="docutils literal"><span class="pre">UT_Always</span></tt> (in configuration: <tt class="docutils literal"><span class="pre">Always</span></tt>)
+Use tabs whenever we need to fill whitespace that spans at least from
+one tab stop to the next one.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="adding-additional-style-options">
+<h2>Adding additional style options<a class="headerlink" href="#adding-additional-style-options" title="Permalink to this headline">¶</a></h2>
+<p>Each additional style option adds costs to the clang-format project. Some of
+these costs affect the clang-format development itself, as we need to make
+sure that any given combination of options work and that new features don’t
+break any of the existing options in any way. There are also costs for end users
+as options become less discoverable and people have to think about and make a
+decision on options they don’t really care about.</p>
+<p>The goal of the clang-format project is more on the side of supporting a
+limited set of styles really well as opposed to supporting every single style
+used by a codebase somewhere in the wild. Of course, we do want to support all
+major projects and thus have established the following bar for adding style
+options. Each new style option must ..</p>
+<blockquote>
+<div><ul class="simple">
+<li>be used in a project of significant size (have dozens of contributors)</li>
+<li>have a publicly accessible style guide</li>
+<li>have a person willing to contribute and maintain patches</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="examples">
+<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
+<p>A style similar to the <a class="reference external" href="https://www.kernel.org/doc/Documentation/CodingStyle">Linux Kernel style</a>:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">BasedOnStyle</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">LLVM</span>
+<span class="l-Scalar-Plain">IndentWidth</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">8</span>
+<span class="l-Scalar-Plain">UseTab</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Always</span>
+<span class="l-Scalar-Plain">BreakBeforeBraces</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Linux</span>
+<span class="l-Scalar-Plain">AllowShortIfStatementsOnASingleLine</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
+<span class="l-Scalar-Plain">IndentCaseLabels</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
+</pre></div>
+</div>
+<p>The result is (imagine that tabs are used for indentation here):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">test</span><span class="p">()</span>
+<span class="p">{</span>
+        <span class="k">switch</span> <span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+        <span class="k">case</span> <span class="mi">0</span>:
+        <span class="k">case</span> <span class="mi">1</span>:
+                <span class="n">do_something</span><span class="p">();</span>
+                <span class="k">break</span><span class="p">;</span>
+        <span class="k">case</span> <span class="mi">2</span>:
+                <span class="n">do_something_else</span><span class="p">();</span>
+                <span class="k">break</span><span class="p">;</span>
+        <span class="nl">default:</span>
+                <span class="k">break</span><span class="p">;</span>
+        <span class="p">}</span>
+        <span class="k">if</span> <span class="p">(</span><span class="n">condition</span><span class="p">)</span>
+                <span class="n">do_something_completely_different</span><span class="p">();</span>
+
+        <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">==</span> <span class="n">y</span><span class="p">)</span> <span class="p">{</span>
+                <span class="n">q</span><span class="p">();</span>
+        <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">></span> <span class="n">y</span><span class="p">)</span> <span class="p">{</span>
+                <span class="n">w</span><span class="p">();</span>
+        <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+                <span class="n">r</span><span class="p">();</span>
+        <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>A style similar to the default Visual Studio formatting style:</p>
+<div class="highlight-yaml"><div class="highlight"><pre><span class="l-Scalar-Plain">UseTab</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Never</span>
+<span class="l-Scalar-Plain">IndentWidth</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">4</span>
+<span class="l-Scalar-Plain">BreakBeforeBraces</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">Allman</span>
+<span class="l-Scalar-Plain">AllowShortIfStatementsOnASingleLine</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
+<span class="l-Scalar-Plain">IndentCaseLabels</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">false</span>
+<span class="l-Scalar-Plain">ColumnLimit</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">0</span>
+</pre></div>
+</div>
+<p>The result is:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">test</span><span class="p">()</span>
+<span class="p">{</span>
+    <span class="k">switch</span> <span class="p">(</span><span class="n">suffix</span><span class="p">)</span>
+    <span class="p">{</span>
+    <span class="k">case</span> <span class="mi">0</span>:
+    <span class="k">case</span> <span class="mi">1</span>:
+        <span class="n">do_something</span><span class="p">();</span>
+        <span class="k">break</span><span class="p">;</span>
+    <span class="k">case</span> <span class="mi">2</span>:
+        <span class="n">do_something_else</span><span class="p">();</span>
+        <span class="k">break</span><span class="p">;</span>
+    <span class="nl">default:</span>
+        <span class="k">break</span><span class="p">;</span>
+    <span class="p">}</span>
+    <span class="k">if</span> <span class="p">(</span><span class="n">condition</span><span class="p">)</span>
+        <span class="n">do_somthing_completely_different</span><span class="p">();</span>
+
+    <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">==</span> <span class="n">y</span><span class="p">)</span>
+    <span class="p">{</span>
+        <span class="n">q</span><span class="p">();</span>
+    <span class="p">}</span>
+    <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="n">x</span> <span class="o">></span> <span class="n">y</span><span class="p">)</span>
+    <span class="p">{</span>
+        <span class="n">w</span><span class="p">();</span>
+    <span class="p">}</span>
+    <span class="k">else</span>
+    <span class="p">{</span>
+        <span class="n">r</span><span class="p">();</span>
+    <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="ClangFormat.html">ClangFormat</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="InternalsManual.html">“Clang” CFE Internals Manual</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/ClangPlugins.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ClangPlugins.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ClangPlugins.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ClangPlugins.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,182 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Clang Plugins — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="next" title="How to write RecursiveASTVisitor based ASTFrontendActions." href="RAVFrontendAction.html" />
+    <link rel="prev" title="LibFormat" href="LibFormat.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Clang Plugins</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="LibFormat.html">LibFormat</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="RAVFrontendAction.html">How to write RecursiveASTVisitor based ASTFrontendActions.</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clang-plugins">
+<h1>Clang Plugins<a class="headerlink" href="#clang-plugins" title="Permalink to this headline">¶</a></h1>
+<p>Clang Plugins make it possible to run extra user defined actions during a
+compilation. This document will provide a basic walkthrough of how to write and
+run a Clang Plugin.</p>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Clang Plugins run FrontendActions over code. See the <a class="reference internal" href="RAVFrontendAction.html"><em>FrontendAction
+tutorial</em></a> on how to write a <tt class="docutils literal"><span class="pre">FrontendAction</span></tt> using the
+<tt class="docutils literal"><span class="pre">RecursiveASTVisitor</span></tt>. In this tutorial, we’ll demonstrate how to write a
+simple clang plugin.</p>
+</div>
+<div class="section" id="writing-a-pluginastaction">
+<h2>Writing a <tt class="docutils literal"><span class="pre">PluginASTAction</span></tt><a class="headerlink" href="#writing-a-pluginastaction" title="Permalink to this headline">¶</a></h2>
+<p>The main difference from writing normal <tt class="docutils literal"><span class="pre">FrontendActions</span></tt> is that you can
+handle plugin command line options. The <tt class="docutils literal"><span class="pre">PluginASTAction</span></tt> base class declares
+a <tt class="docutils literal"><span class="pre">ParseArgs</span></tt> method which you have to implement in your plugin.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="nf">ParseArgs</span><span class="p">(</span><span class="k">const</span> <span class="n">CompilerInstance</span> <span class="o">&</span><span class="n">CI</span><span class="p">,</span>
+               <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">>&</span> <span class="n">args</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">e</span> <span class="o">=</span> <span class="n">args</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+    <span class="k">if</span> <span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">==</span> <span class="s">"-some-arg"</span><span class="p">)</span> <span class="p">{</span>
+      <span class="c1">// Handle the command line argument.</span>
+    <span class="p">}</span>
+  <span class="p">}</span>
+  <span class="k">return</span> <span class="nb">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="registering-a-plugin">
+<h2>Registering a plugin<a class="headerlink" href="#registering-a-plugin" title="Permalink to this headline">¶</a></h2>
+<p>A plugin is loaded from a dynamic library at runtime by the compiler. To
+register a plugin in a library, use <tt class="docutils literal"><span class="pre">FrontendPluginRegistry::Add<></span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">FrontendPluginRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyPlugin</span><span class="o">></span> <span class="n">X</span><span class="p">(</span><span class="s">"my-plugin-name"</span><span class="p">,</span> <span class="s">"my plugin description"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="defining-pragmas">
+<h2>Defining pragmas<a class="headerlink" href="#defining-pragmas" title="Permalink to this headline">¶</a></h2>
+<p>Plugins can also define pragmas by declaring a <tt class="docutils literal"><span class="pre">PragmaHandler</span></tt> and
+registering it using <tt class="docutils literal"><span class="pre">PragmaHandlerRegistry::Add<></span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Define a pragma handler for #pragma example_pragma</span>
+<span class="k">class</span> <span class="nc">ExamplePragmaHandler</span> <span class="o">:</span> <span class="k">public</span> <span class="n">PragmaHandler</span> <span class="p">{</span>
+<span class="nl">public:</span>
+  <span class="n">ExamplePragmaHandler</span><span class="p">()</span> <span class="o">:</span> <span class="n">PragmaHandler</span><span class="p">(</span><span class="s">"example_pragma"</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
+  <span class="kt">void</span> <span class="n">HandlePragma</span><span class="p">(</span><span class="n">Preprocessor</span> <span class="o">&</span><span class="n">PP</span><span class="p">,</span> <span class="n">PragmaIntroducerKind</span> <span class="n">Introducer</span><span class="p">,</span>
+                    <span class="n">Token</span> <span class="o">&</span><span class="n">PragmaTok</span><span class="p">)</span> <span class="p">{</span>
+    <span class="c1">// Handle the pragma</span>
+  <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="k">static</span> <span class="n">PragmaHandlerRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">ExamplePragmaHandler</span><span class="o">></span> <span class="n">Y</span><span class="p">(</span><span class="s">"example_pragma"</span><span class="p">,</span><span class="s">"example pragma description"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="putting-it-all-together">
+<h2>Putting it all together<a class="headerlink" href="#putting-it-all-together" title="Permalink to this headline">¶</a></h2>
+<p>Let’s look at an example plugin that prints top-level function names.  This
+example is checked into the clang repository; please take a look at
+the <a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup">latest version of PrintFunctionNames.cpp</a>.</p>
+</div>
+<div class="section" id="running-the-plugin">
+<h2>Running the plugin<a class="headerlink" href="#running-the-plugin" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="using-the-cc1-command-line">
+<h3>Using the cc1 command line<a class="headerlink" href="#using-the-cc1-command-line" title="Permalink to this headline">¶</a></h3>
+<p>To run a plugin, the dynamic library containing the plugin registry must be
+loaded via the <cite>-load</cite> command line option. This will load all plugins
+that are registered, and you can select the plugins to run by specifying the
+<cite>-plugin</cite> option. Additional parameters for the plugins can be passed with
+<cite>-plugin-arg-<plugin-name></cite>.</p>
+<p>Note that those options must reach clang’s cc1 process. There are two
+ways to do so:</p>
+<ul class="simple">
+<li>Directly call the parsing process by using the <cite>-cc1</cite> option; this
+has the downside of not configuring the default header search paths, so
+you’ll need to specify the full system path configuration on the command
+line.</li>
+<li>Use clang as usual, but prefix all arguments to the cc1 process with
+<cite>-Xclang</cite>.</li>
+</ul>
+<p>For example, to run the <tt class="docutils literal"><span class="pre">print-function-names</span></tt> plugin over a source file in
+clang, first build the plugin, and then call clang with the plugin from the
+source tree:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nb">export </span><span class="nv">BD</span><span class="o">=</span>/path/to/build/directory
+<span class="gp">$</span> <span class="o">(</span><span class="nb">cd</span> <span class="nv">$BD</span> <span class="o">&&</span> make PrintFunctionNames <span class="o">)</span>
+<span class="gp">$</span> clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS <span class="se">\</span>
+<span class="go">          -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \</span>
+<span class="go">          -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \</span>
+<span class="go">          tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \</span>
+<span class="go">          -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \</span>
+<span class="go">          -plugin -Xclang print-fns</span>
+</pre></div>
+</div>
+<p>Also see the print-function-name plugin example’s
+<a class="reference external" href="http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup">README</a></p>
+</div>
+<div class="section" id="using-the-clang-command-line">
+<h3>Using the clang command line<a class="headerlink" href="#using-the-clang-command-line" title="Permalink to this headline">¶</a></h3>
+<p>Using <cite>-fplugin=plugin</cite> on the clang command line passes the plugin
+through as an argument to <cite>-load</cite> on the cc1 command line. If the plugin
+class implements the <tt class="docutils literal"><span class="pre">getActionType</span></tt> method then the plugin is run
+automatically. For example, to run the plugin automatically after the main AST
+action (i.e. the same as using <cite>-add-plugin</cite>):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Automatically run the plugin after the main AST action</span>
+<span class="n">PluginASTAction</span><span class="o">::</span><span class="n">ActionType</span> <span class="n">getActionType</span><span class="p">()</span> <span class="n">override</span> <span class="p">{</span>
+  <span class="k">return</span> <span class="n">AddAfterMainAction</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="LibFormat.html">LibFormat</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="RAVFrontendAction.html">How to write RecursiveASTVisitor based ASTFrontendActions.</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/ClangTools.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ClangTools.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ClangTools.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ClangTools.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,220 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Overview — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="next" title="ClangCheck" href="ClangCheck.html" />
+    <link rel="prev" title="JSON Compilation Database Format Specification" href="JSONCompilationDatabase.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Overview</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangCheck.html">ClangCheck</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="overview">
+<h1>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h1>
+<p>Clang Tools are standalone command line (and potentially GUI) tools
+designed for use by C++ developers who are already using and enjoying
+Clang as their compiler. These tools provide developer-oriented
+functionality such as fast syntax checking, automatic formatting,
+refactoring, etc.</p>
+<p>Only a couple of the most basic and fundamental tools are kept in the
+primary Clang Subversion project. The rest of the tools are kept in a
+side-project so that developers who don’t want or need to build them
+don’t. If you want to get access to the extra Clang Tools repository,
+simply check it out into the tools tree of your Clang checkout and
+follow the usual process for building and working with a combined
+LLVM/Clang checkout:</p>
+<ul class="simple">
+<li>With Subversion:<ul>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/tools/clang/tools</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">http://llvm.org/svn/llvm-project/clang-tools-extra/trunk</span> <span class="pre">extra</span></tt></li>
+</ul>
+</li>
+<li>Or with Git:<ul>
+<li><tt class="docutils literal"><span class="pre">cd</span> <span class="pre">llvm/tools/clang/tools</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">http://llvm.org/git/clang-tools-extra.git</span> <span class="pre">extra</span></tt></li>
+</ul>
+</li>
+</ul>
+<p>This document describes a high-level overview of the organization of
+Clang Tools within the project as well as giving an introduction to some
+of the more important tools. However, it should be noted that this
+document is currently focused on Clang and Clang Tool developers, not on
+end users of these tools.</p>
+<div class="section" id="clang-tools-organization">
+<h2>Clang Tools Organization<a class="headerlink" href="#clang-tools-organization" title="Permalink to this headline">¶</a></h2>
+<p>Clang Tools are CLI or GUI programs that are intended to be directly
+used by C++ developers. That is they are <em>not</em> primarily for use by
+Clang developers, although they are hopefully useful to C++ developers
+who happen to work on Clang, and we try to actively dogfood their
+functionality. They are developed in three components: the underlying
+infrastructure for building a standalone tool based on Clang, core
+shared logic used by many different tools in the form of refactoring and
+rewriting libraries, and the tools themselves.</p>
+<p>The underlying infrastructure for Clang Tools is the
+<a class="reference internal" href="LibTooling.html"><em>LibTooling</em></a> platform. See its documentation for much
+more detailed information about how this infrastructure works. The
+common refactoring and rewriting toolkit-style library is also part of
+LibTooling organizationally.</p>
+<p>A few Clang Tools are developed along side the core Clang libraries as
+examples and test cases of fundamental functionality. However, most of
+the tools are developed in a side repository to provide easy separation
+from the core libraries. We intentionally do not support public
+libraries in the side repository, as we want to carefully review and
+find good APIs for libraries as they are lifted out of a few tools and
+into the core Clang library set.</p>
+<p>Regardless of which repository Clang Tools’ code resides in, the
+development process and practices for all Clang Tools are exactly those
+of Clang itself. They are entirely within the Clang <em>project</em>,
+regardless of the version control scheme.</p>
+</div>
+<div class="section" id="core-clang-tools">
+<h2>Core Clang Tools<a class="headerlink" href="#core-clang-tools" title="Permalink to this headline">¶</a></h2>
+<p>The core set of Clang tools that are within the main repository are
+tools that very specifically complement, and allow use and testing of
+<em>Clang</em> specific functionality.</p>
+<div class="section" id="clang-check">
+<h3><tt class="docutils literal"><span class="pre">clang-check</span></tt><a class="headerlink" href="#clang-check" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference internal" href="ClangCheck.html"><em>ClangCheck</em></a> combines the LibTooling framework for running a
+Clang tool with the basic Clang diagnostics by syntax checking specific files
+in a fast, command line interface. It can also accept flags to re-display the
+diagnostics in different formats with different flags, suitable for use driving
+an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply
+fixit-hints offered by clang. See <a class="reference internal" href="HowToSetupToolingForLLVM.html"><em>How To Setup Clang Tooling For LLVM</em></a> for
+instructions on how to setup and used <cite>clang-check</cite>.</p>
+</div>
+<div class="section" id="clang-format">
+<h3><tt class="docutils literal"><span class="pre">clang-format</span></tt><a class="headerlink" href="#clang-format" title="Permalink to this headline">¶</a></h3>
+<p>Clang-format is both a <a class="reference internal" href="LibFormat.html"><em>library</em></a> and a <a class="reference internal" href="ClangFormat.html"><em>stand-alone tool</em></a> with the goal of automatically reformatting C++ sources files
+according to configurable style guides.  To do so, clang-format uses Clang’s
+<tt class="docutils literal"><span class="pre">Lexer</span></tt> to transform an input file into a token stream and then changes all
+the whitespace around those tokens.  The goal is for clang-format to serve both
+as a user tool (ideally with powerful IDE integrations) and as part of other
+refactoring tools, e.g. to do a reformatting of all the lines changed during a
+renaming.</p>
+</div>
+</div>
+<div class="section" id="extra-clang-tools">
+<h2>Extra Clang Tools<a class="headerlink" href="#extra-clang-tools" title="Permalink to this headline">¶</a></h2>
+<p>As various categories of Clang Tools are added to the extra repository,
+they’ll be tracked here. The focus of this documentation is on the scope
+and features of the tools for other tool developers; each tool should
+provide its own user-focused documentation.</p>
+<div class="section" id="clang-tidy">
+<h3><tt class="docutils literal"><span class="pre">clang-tidy</span></tt><a class="headerlink" href="#clang-tidy" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://clang.llvm.org/extra/clang-tidy/">clang-tidy</a> is a clang-based C++
+linter tool. It provides an extensible framework for building compiler-based
+static analyses detecting and fixing bug-prone patterns, performance,
+portability and maintainability issues.</p>
+</div>
+</div>
+<div class="section" id="ideas-for-new-tools">
+<h2>Ideas for new Tools<a class="headerlink" href="#ideas-for-new-tools" title="Permalink to this headline">¶</a></h2>
+<ul>
+<li><p class="first">C++ cast conversion tool.  Will convert C-style casts (<tt class="docutils literal"><span class="pre">(type)</span> <span class="pre">value</span></tt>) to
+appropriate C++ cast (<tt class="docutils literal"><span class="pre">static_cast</span></tt>, <tt class="docutils literal"><span class="pre">const_cast</span></tt> or
+<tt class="docutils literal"><span class="pre">reinterpret_cast</span></tt>).</p>
+</li>
+<li><p class="first">Non-member <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt> conversion tool.  Will convert
+<tt class="docutils literal"><span class="pre">foo.begin()</span></tt> into <tt class="docutils literal"><span class="pre">begin(foo)</span></tt> and similarly for <tt class="docutils literal"><span class="pre">end()</span></tt>, where
+<tt class="docutils literal"><span class="pre">foo</span></tt> is a standard container.  We could also detect similar patterns for
+arrays.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">tr1</span></tt> removal tool.  Will migrate source code from using TR1 library
+features to C++11 library.  For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <tr1/unordered_map></span>
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span>
+<span class="p">{</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">tr1</span><span class="o">::</span><span class="n">unordered_map</span> <span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="kt">int</span><span class="o">></span> <span class="n">ma</span><span class="p">;</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">ma</span><span class="p">.</span><span class="n">size</span> <span class="p">()</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
+    <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>should be rewritten to:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <unordered_map></span>
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span>
+<span class="p">{</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">unordered_map</span> <span class="o"><</span><span class="kt">int</span><span class="p">,</span> <span class="kt">int</span><span class="o">></span> <span class="n">ma</span><span class="p">;</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">ma</span><span class="p">.</span><span class="n">size</span> <span class="p">()</span> <span class="o"><<</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
+    <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">A tool to remove <tt class="docutils literal"><span class="pre">auto</span></tt>.  Will convert <tt class="docutils literal"><span class="pre">auto</span></tt> to an explicit type or add
+comments with deduced types.  The motivation is that there are developers
+that don’t want to use <tt class="docutils literal"><span class="pre">auto</span></tt> because they are afraid that they might lose
+control over their code.</p>
+</li>
+<li><p class="first">C++14: less verbose operator function objects (<a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3421.htm">N3421</a>).
+For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">sort</span><span class="p">(</span><span class="n">v</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">v</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="n">greater</span><span class="o"><</span><span class="n">ValueType</span><span class="o">></span><span class="p">());</span>
+</pre></div>
+</div>
+<p>should be rewritten to:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">sort</span><span class="p">(</span><span class="n">v</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">v</span><span class="p">.</span><span class="n">end</span><span class="p">(),</span> <span class="n">greater</span><span class="o"><></span><span class="p">());</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="JSONCompilationDatabase.html">JSON Compilation Database Format Specification</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ClangCheck.html">ClangCheck</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/CommandGuide/clang.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/CommandGuide/clang.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/CommandGuide/clang.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/CommandGuide/clang.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,705 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>clang - the Clang C, C++, and Objective-C compiler — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="../_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '../',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="../_static/jquery.js"></script>
+    <script type="text/javascript" src="../_static/underscore.js"></script>
+    <script type="text/javascript" src="../_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="../index.html" />
+    <link rel="up" title="Clang “man” pages" href="index.html" />
+    <link rel="next" title="Frequently Asked Questions (FAQ)" href="../FAQ.html" />
+    <link rel="prev" title="Clang “man” pages" href="index.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="../index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>clang - the Clang C, C++, and Objective-C compiler</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="index.html">Clang “man” pages</a>
+          ::  
+        <a class="uplink" href="../index.html">Contents</a>
+          ::  
+        <a href="../FAQ.html">Frequently Asked Questions (FAQ)</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clang-the-clang-c-c-and-objective-c-compiler">
+<h1>clang - the Clang C, C++, and Objective-C compiler<a class="headerlink" href="#clang-the-clang-c-c-and-objective-c-compiler" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">clang</strong> [<em>options</em>] <em>filename ...</em></p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">clang</strong> is a C, C++, and Objective-C compiler which encompasses
+preprocessing, parsing, optimization, code generation, assembly, and linking.
+Depending on which high-level mode setting is passed, Clang will stop before
+doing a full link.  While Clang is highly integrated, it is important to
+understand the stages of compilation, to understand how to invoke it.  These
+stages are:</p>
+<dl class="docutils">
+<dt>Driver</dt>
+<dd>The clang executable is actually a small driver which controls the overall
+execution of other tools such as the compiler, assembler and linker.
+Typically you do not need to interact with the driver, but you
+transparently use it to run the other tools.</dd>
+<dt>Preprocessing</dt>
+<dd>This stage handles tokenization of the input source file, macro expansion,
+#include expansion and handling of other preprocessor directives.  The
+output of this stage is typically called a ”.i” (for C), ”.ii” (for C++),
+”.mi” (for Objective-C), or ”.mii” (for Objective-C++) file.</dd>
+<dt>Parsing and Semantic Analysis</dt>
+<dd>This stage parses the input file, translating preprocessor tokens into a
+parse tree.  Once in the form of a parse tree, it applies semantic
+analysis to compute types for expressions as well and determine whether
+the code is well formed. This stage is responsible for generating most of
+the compiler warnings as well as parse errors. The output of this stage is
+an “Abstract Syntax Tree” (AST).</dd>
+<dt>Code Generation and Optimization</dt>
+<dd><p class="first">This stage translates an AST into low-level intermediate code (known as
+“LLVM IR”) and ultimately to machine code.  This phase is responsible for
+optimizing the generated code and handling target-specific code generation.
+The output of this stage is typically called a ”.s” file or “assembly” file.</p>
+<p class="last">Clang also supports the use of an integrated assembler, in which the code
+generator produces object files directly. This avoids the overhead of
+generating the ”.s” file and of calling the target assembler.</p>
+</dd>
+<dt>Assembler</dt>
+<dd>This stage runs the target assembler to translate the output of the
+compiler into a target object file. The output of this stage is typically
+called a ”.o” file or “object” file.</dd>
+<dt>Linker</dt>
+<dd>This stage runs the target linker to merge multiple object files into an
+executable or dynamic library. The output of this stage is typically called
+an “a.out”, ”.dylib” or ”.so” file.</dd>
+</dl>
+<p><strong class="program">Clang Static Analyzer</strong></p>
+<p>The Clang Static Analyzer is a tool that scans source code to try to find bugs
+through code analysis.  This tool uses many parts of Clang and is built into
+the same driver.  Please see <<a class="reference external" href="http://clang-analyzer.llvm.org">http://clang-analyzer.llvm.org</a>> for more details
+on how to use the static analyzer.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="stage-selection-options">
+<h3>Stage Selection Options<a class="headerlink" href="#stage-selection-options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-E">
+<tt class="descname">-E</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-E" title="Permalink to this definition">¶</a></dt>
+<dd><p>Run the preprocessor stage.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fsyntax-only">
+<tt class="descname">-fsyntax-only</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fsyntax-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Run the preprocessor, parser and type checking stages.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-S">
+<tt class="descname">-S</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-S" title="Permalink to this definition">¶</a></dt>
+<dd><p>Run the previous stages as well as LLVM generation and optimization stages
+and target-specific code generation, producing an assembly file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-c">
+<tt class="descname">-c</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-c" title="Permalink to this definition">¶</a></dt>
+<dd><p>Run all of the above, plus the assembler, generating a target ”.o” object file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-arg-no">
+<tt class="descname">no</tt><tt class="descclassname"> stage selection option</tt><a class="headerlink" href="#cmdoption-arg-no" title="Permalink to this definition">¶</a></dt>
+<dd><p>If no stage selection option is specified, all stages above are run, and the
+linker is run to combine the results into an executable or shared library.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="language-selection-and-mode-options">
+<h3>Language Selection and Mode Options<a class="headerlink" href="#language-selection-and-mode-options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-x">
+<tt class="descname">-x</tt><tt class="descclassname"> <language></tt><a class="headerlink" href="#cmdoption-x" title="Permalink to this definition">¶</a></dt>
+<dd><p>Treat subsequent input files as having type language.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-std">
+<tt class="descname">-std</tt><tt class="descclassname">=<language></tt><a class="headerlink" href="#cmdoption-std" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the language standard to compile for.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-stdlib">
+<tt class="descname">-stdlib</tt><tt class="descclassname">=<library></tt><a class="headerlink" href="#cmdoption-stdlib" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the C++ standard library to use; supported options are libstdc++ and
+libc++. If not specified, platform default will be used.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-rtlib">
+<tt class="descname">-rtlib</tt><tt class="descclassname">=<library></tt><a class="headerlink" href="#cmdoption-rtlib" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the compiler runtime library to use; supported options are libgcc and
+compiler-rt. If not specified, platform default will be used.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ansi">
+<tt class="descname">-ansi</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ansi" title="Permalink to this definition">¶</a></dt>
+<dd><p>Same as -std=c89.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ObjC">
+<span id="cmdoption-ObjC"></span><tt class="descname">-ObjC</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-ObjC</tt><tt class="descclassname">++</tt><a class="headerlink" href="#cmdoption-ObjC" title="Permalink to this definition">¶</a></dt>
+<dd><p>Treat source input files as Objective-C and Object-C++ inputs respectively.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-trigraphs">
+<tt class="descname">-trigraphs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-trigraphs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable trigraphs.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ffreestanding">
+<tt class="descname">-ffreestanding</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ffreestanding" title="Permalink to this definition">¶</a></dt>
+<dd><p>Indicate that the file should be compiled for a freestanding, not a hosted,
+environment.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-builtin">
+<tt class="descname">-fno-builtin</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fno-builtin" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable special handling and optimizations of builtin functions like
+<tt class="xref c c-func docutils literal"><span class="pre">strlen()</span></tt> and <tt class="xref c c-func docutils literal"><span class="pre">malloc()</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fmath-errno">
+<tt class="descname">-fmath-errno</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fmath-errno" title="Permalink to this definition">¶</a></dt>
+<dd><p>Indicate that math functions should be treated as updating <tt class="xref c c-data docutils literal"><span class="pre">errno</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fpascal-strings">
+<tt class="descname">-fpascal-strings</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fpascal-strings" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable support for Pascal-style strings with “\pfoo”.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fms-extensions">
+<tt class="descname">-fms-extensions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fms-extensions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable support for Microsoft extensions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fmsc-version">
+<tt class="descname">-fmsc-version</tt><tt class="descclassname">=</tt><a class="headerlink" href="#cmdoption-fmsc-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fborland-extensions">
+<tt class="descname">-fborland-extensions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fborland-extensions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable support for Borland extensions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fwritable-strings">
+<tt class="descname">-fwritable-strings</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fwritable-strings" title="Permalink to this definition">¶</a></dt>
+<dd><p>Make all string literals default to writable.  This disables uniquing of
+strings and other optimizations.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-flax-vector-conversions">
+<tt class="descname">-flax-vector-conversions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-flax-vector-conversions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Allow loose type checking rules for implicit vector conversions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fblocks">
+<tt class="descname">-fblocks</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fblocks" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable the “Blocks” language feature.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fobjc-abi-version">
+<tt class="descname">-fobjc-abi-version</tt><tt class="descclassname">=version</tt><a class="headerlink" href="#cmdoption-fobjc-abi-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select the Objective-C ABI version to use. Available versions are 1 (legacy
+“fragile” ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fobjc-nonfragile-abi-version">
+<tt class="descname">-fobjc-nonfragile-abi-version</tt><tt class="descclassname">=<version></tt><a class="headerlink" href="#cmdoption-fobjc-nonfragile-abi-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select the Objective-C non-fragile ABI version to use by default. This will
+only be used as the Objective-C ABI when the non-fragile ABI is enabled
+(either via <a class="reference internal" href="#cmdoption-fobjc-nonfragile-abi"><em class="xref std std-option">-fobjc-nonfragile-abi</em></a>, or because it is the platform
+default).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fobjc-nonfragile-abi">
+<span id="cmdoption-fno-objc-nonfragile-abi"></span><tt class="descname">-fobjc-nonfragile-abi</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-fno-objc-nonfragile-abi</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fobjc-nonfragile-abi" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable use of the Objective-C non-fragile ABI. On platforms for which this is
+the default ABI, it can be disabled with <a class="reference internal" href="#cmdoption-fno-objc-nonfragile-abi"><em class="xref std std-option">-fno-objc-nonfragile-abi</em></a>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="target-selection-options">
+<h3>Target Selection Options<a class="headerlink" href="#target-selection-options" title="Permalink to this headline">¶</a></h3>
+<p>Clang fully supports cross compilation as an inherent part of its design.
+Depending on how your version of Clang is configured, it may have support for a
+number of cross compilers, or may only support a native target.</p>
+<dl class="option">
+<dt id="cmdoption-arch">
+<tt class="descname">-arch</tt><tt class="descclassname"> <architecture></tt><a class="headerlink" href="#cmdoption-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the architecture to build for.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mmacosx-version-min">
+<tt class="descname">-mmacosx-version-min</tt><tt class="descclassname">=<version></tt><a class="headerlink" href="#cmdoption-mmacosx-version-min" title="Permalink to this definition">¶</a></dt>
+<dd><p>When building for Mac OS X, specify the minimum version supported by your
+application.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-miphoneos-version-min">
+<tt class="descname">-miphoneos-version-min</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-miphoneos-version-min" title="Permalink to this definition">¶</a></dt>
+<dd><p>When building for iPhone OS, specify the minimum version supported by your
+application.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-march">
+<tt class="descname">-march</tt><tt class="descclassname">=<cpu></tt><a class="headerlink" href="#cmdoption-march" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify that Clang should generate code for a specific processor family
+member and later.  For example, if you specify -march=i486, the compiler is
+allowed to generate instructions that are valid on i486 and later processors,
+but which may not exist on earlier ones.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="code-generation-options">
+<h3>Code Generation Options<a class="headerlink" href="#code-generation-options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-O0">
+<span id="cmdoption-O1"></span><span id="cmdoption-O2"></span><span id="cmdoption-O3"></span><span id="cmdoption-Ofast"></span><span id="cmdoption-Os"></span><span id="cmdoption-Oz"></span><span id="cmdoption-Og"></span><span id="cmdoption-O"></span><span id="cmdoption-O4"></span><tt class="descname">-O0</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-O1</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-O2</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-O3</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-Ofast</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-Os</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-Oz</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-Og</tt><tt class="descclassname"></tt><t
 t class="descclassname">, </tt><tt class="descname">-O</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-O4</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-O0" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify which optimization level to use:</p>
+<blockquote>
+<div><p><a class="reference internal" href="#cmdoption-O0"><em class="xref std std-option">-O0</em></a> Means “no optimization”: this level compiles the fastest and
+generates the most debuggable code.</p>
+<p><a class="reference internal" href="#cmdoption-O1"><em class="xref std std-option">-O1</em></a> Somewhere between <a class="reference internal" href="#cmdoption-O0"><em class="xref std std-option">-O0</em></a> and <a class="reference internal" href="#cmdoption-O2"><em class="xref std std-option">-O2</em></a>.</p>
+<p><a class="reference internal" href="#cmdoption-O2"><em class="xref std std-option">-O2</em></a> Moderate level of optimization which enables most
+optimizations.</p>
+<p><a class="reference internal" href="#cmdoption-O3"><em class="xref std std-option">-O3</em></a> Like <a class="reference internal" href="#cmdoption-O2"><em class="xref std std-option">-O2</em></a>, except that it enables optimizations that
+take longer to perform or that may generate larger code (in an attempt to
+make the program run faster).</p>
+<p><a class="reference internal" href="#cmdoption-Ofast"><em class="xref std std-option">-Ofast</em></a> Enables all the optimizations from <a class="reference internal" href="#cmdoption-O3"><em class="xref std std-option">-O3</em></a> along
+with other aggressive optimizations that may violate strict compliance with
+language standards.</p>
+<p><a class="reference internal" href="#cmdoption-Os"><em class="xref std std-option">-Os</em></a> Like <a class="reference internal" href="#cmdoption-O2"><em class="xref std std-option">-O2</em></a> with extra optimizations to reduce code
+size.</p>
+<p><a class="reference internal" href="#cmdoption-Oz"><em class="xref std std-option">-Oz</em></a> Like <a class="reference internal" href="#cmdoption-Os"><em class="xref std std-option">-Os</em></a> (and thus <a class="reference internal" href="#cmdoption-O2"><em class="xref std std-option">-O2</em></a>), but reduces code
+size further.</p>
+<p><a class="reference internal" href="#cmdoption-Og"><em class="xref std std-option">-Og</em></a> Like <a class="reference internal" href="#cmdoption-O1"><em class="xref std std-option">-O1</em></a>. In future versions, this option might
+disable different optimizations in order to improve debuggability.</p>
+<p><a class="reference internal" href="#cmdoption-O"><em class="xref std std-option">-O</em></a> Equivalent to <a class="reference internal" href="#cmdoption-O2"><em class="xref std std-option">-O2</em></a>.</p>
+<p><a class="reference internal" href="#cmdoption-O4"><em class="xref std std-option">-O4</em></a> and higher</p>
+<blockquote>
+<div>Currently equivalent to <a class="reference internal" href="#cmdoption-O3"><em class="xref std std-option">-O3</em></a></div></blockquote>
+</div></blockquote>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-g">
+<span id="cmdoption-gline-tables-only"></span><span id="cmdoption-gmodules"></span><tt class="descname">-g</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-gline-tables-only</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-gmodules</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-g" title="Permalink to this definition">¶</a></dt>
+<dd><p>Control debug information output.  Note that Clang debug information works
+best at <a class="reference internal" href="#cmdoption-O0"><em class="xref std std-option">-O0</em></a>.  When more than one option starting with <cite>-g</cite> is
+specified, the last one wins:</p>
+<blockquote>
+<div><p><a class="reference internal" href="../UsersManual.html#cmdoption-g"><em class="xref std std-option">-g</em></a> Generate debug information.</p>
+<p><a class="reference internal" href="../UsersManual.html#cmdoption-gline-tables-only"><em class="xref std std-option">-gline-tables-only</em></a> Generate only line table debug information. This
+allows for symbolicated backtraces with inlining information, but does not
+include any information about variables, their locations or types.</p>
+<p><a class="reference internal" href="#cmdoption-gmodules"><em class="xref std std-option">-gmodules</em></a> Generate debug information that contains external
+references to types defined in Clang modules or precompiled headers instead
+of emitting redundant debug type information into every object file.  This
+option transparently switches the Clang module format to object file
+containers that hold the Clang module together with the debug information.
+When compiling a program that uses Clang modules or precompiled headers,
+this option produces complete debug information with faster compile
+times and much smaller object files.</p>
+<p>This option should not be used when building static libraries for
+distribution to other machines because the debug info will contain
+references to the module cache on the machine the object files in the
+library were built on.</p>
+</div></blockquote>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fstandalone-debug">
+<tt class="descname">-fstandalone-debug</tt><tt class="descclassname"> -fno-standalone-debug</tt><a class="headerlink" href="#cmdoption-fstandalone-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>Clang supports a number of optimizations to reduce the size of debug
+information in the binary. They work based on the assumption that the
+debug type information can be spread out over multiple compilation units.
+For instance, Clang will not emit type definitions for types that are not
+needed by a module and could be replaced with a forward declaration.
+Further, Clang will only emit type info for a dynamic C++ class in the
+module that contains the vtable for the class.</p>
+<p>The <a class="reference internal" href="../UsersManual.html#cmdoption-fstandalone-debug"><em class="xref std std-option">-fstandalone-debug</em></a> option turns off these optimizations.
+This is useful when working with 3rd-party libraries that don’t come with
+debug information.  This is the default on Darwin.  Note that Clang will
+never emit type information for types that are not referenced at all by the
+program.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fexceptions">
+<tt class="descname">-fexceptions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fexceptions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable generation of unwind information. This allows exceptions to be thrown
+through Clang compiled stack frames.  This is on by default in x86-64.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftrapv">
+<tt class="descname">-ftrapv</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ftrapv" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate code to catch integer overflow errors.  Signed integer overflow is
+undefined in C. With this flag, extra code is generated to detect this and
+abort when it happens.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fvisibility">
+<tt class="descname">-fvisibility</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fvisibility" title="Permalink to this definition">¶</a></dt>
+<dd><p>This flag sets the default visibility level.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fcommon">
+<span id="cmdoption-fno-common"></span><tt class="descname">-fcommon</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-fno-common</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fcommon" title="Permalink to this definition">¶</a></dt>
+<dd><p>This flag specifies that variables without initializers get common linkage.
+It can be disabled with <a class="reference internal" href="#cmdoption-fno-common"><em class="xref std std-option">-fno-common</em></a>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftls-model">
+<tt class="descname">-ftls-model</tt><tt class="descclassname">=<model></tt><a class="headerlink" href="#cmdoption-ftls-model" title="Permalink to this definition">¶</a></dt>
+<dd><p>Set the default thread-local storage (TLS) model to use for thread-local
+variables. Valid values are: “global-dynamic”, “local-dynamic”,
+“initial-exec” and “local-exec”. The default is “global-dynamic”. The default
+model can be overridden with the tls_model attribute. The compiler will try
+to choose a more efficient model if possible.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-flto">
+<span id="cmdoption-flto"></span><span id="cmdoption-flto"></span><span id="cmdoption-emit-llvm"></span><tt class="descname">-flto</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-flto</tt><tt class="descclassname">=full</tt><tt class="descclassname">, </tt><tt class="descname">-flto</tt><tt class="descclassname">=thin</tt><tt class="descclassname">, </tt><tt class="descname">-emit-llvm</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-flto" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate output files in LLVM formats, suitable for link time optimization.
+When used with <a class="reference internal" href="#cmdoption-S"><em class="xref std std-option">-S</em></a> this generates LLVM intermediate language
+assembly files, otherwise this generates LLVM bitcode format object files
+(which may be passed to the linker depending on the stage selection options).</p>
+<p>The default for <a class="reference internal" href="#cmdoption-flto"><em class="xref std std-option">-flto</em></a> is “full”, in which the
+LLVM bitcode is suitable for monolithic Link Time Optimization (LTO), where
+the linker merges all such modules into a single combined module for
+optimization. With “thin”, <a class="reference internal" href="../ThinLTO.html"><em>ThinLTO</em></a>
+compilation is invoked instead.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="driver-options">
+<h3>Driver Options<a class="headerlink" href="#driver-options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-">
+<tt class="descname">-</tt><tt class="descclassname">###</tt><a class="headerlink" href="#cmdoption-" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print (but do not run) the commands to run for this compilation.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption--help">
+<tt class="descname">--help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption--help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display available options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Qunused-arguments">
+<tt class="descname">-Qunused-arguments</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Qunused-arguments" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not emit any warnings for unused driver arguments.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wa">
+<tt class="descname">-Wa</tt><tt class="descclassname">,<args></tt><a class="headerlink" href="#cmdoption-Wa" title="Permalink to this definition">¶</a></dt>
+<dd><p>Pass the comma separated arguments in args to the assembler.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wl">
+<tt class="descname">-Wl</tt><tt class="descclassname">,<args></tt><a class="headerlink" href="#cmdoption-Wl" title="Permalink to this definition">¶</a></dt>
+<dd><p>Pass the comma separated arguments in args to the linker.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wp">
+<tt class="descname">-Wp</tt><tt class="descclassname">,<args></tt><a class="headerlink" href="#cmdoption-Wp" title="Permalink to this definition">¶</a></dt>
+<dd><p>Pass the comma separated arguments in args to the preprocessor.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Xanalyzer">
+<tt class="descname">-Xanalyzer</tt><tt class="descclassname"> <arg></tt><a class="headerlink" href="#cmdoption-Xanalyzer" title="Permalink to this definition">¶</a></dt>
+<dd><p>Pass arg to the static analyzer.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Xassembler">
+<tt class="descname">-Xassembler</tt><tt class="descclassname"> <arg></tt><a class="headerlink" href="#cmdoption-Xassembler" title="Permalink to this definition">¶</a></dt>
+<dd><p>Pass arg to the assembler.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Xlinker">
+<tt class="descname">-Xlinker</tt><tt class="descclassname"> <arg></tt><a class="headerlink" href="#cmdoption-Xlinker" title="Permalink to this definition">¶</a></dt>
+<dd><p>Pass arg to the linker.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Xpreprocessor">
+<tt class="descname">-Xpreprocessor</tt><tt class="descclassname"> <arg></tt><a class="headerlink" href="#cmdoption-Xpreprocessor" title="Permalink to this definition">¶</a></dt>
+<dd><p>Pass arg to the preprocessor.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-o">
+<tt class="descname">-o</tt><tt class="descclassname"> <file></tt><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Write output to file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-print-file-name">
+<tt class="descname">-print-file-name</tt><tt class="descclassname">=<file></tt><a class="headerlink" href="#cmdoption-print-file-name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the full library path of file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-print-libgcc-file-name">
+<tt class="descname">-print-libgcc-file-name</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-print-libgcc-file-name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the library path for the currently used compiler runtime library
+(“libgcc.a” or “libclang_rt.builtins.*.a”).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-print-prog-name">
+<tt class="descname">-print-prog-name</tt><tt class="descclassname">=<name></tt><a class="headerlink" href="#cmdoption-print-prog-name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the full program path of name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-print-search-dirs">
+<tt class="descname">-print-search-dirs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-print-search-dirs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the paths used for finding libraries and programs.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-save-temps">
+<tt class="descname">-save-temps</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-save-temps" title="Permalink to this definition">¶</a></dt>
+<dd><p>Save intermediate compilation results.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-save-stats">
+<span id="cmdoption-save-stats"></span><span id="cmdoption-save-stats"></span><tt class="descname">-save-stats</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-save-stats</tt><tt class="descclassname">=cwd</tt><tt class="descclassname">, </tt><tt class="descname">-save-stats</tt><tt class="descclassname">=obj</tt><a class="headerlink" href="#cmdoption-save-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Save internal code generation (LLVM) statistics to a file in the current
+directory (<a class="reference internal" href="#cmdoption-save-stats"><em class="xref std std-option">-save-stats</em></a>/”-save-stats=cwd”) or the directory
+of the output file (“-save-state=obj”).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-integrated-as">
+<span id="cmdoption-no-integrated-as"></span><tt class="descname">-integrated-as</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-no-integrated-as</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-integrated-as" title="Permalink to this definition">¶</a></dt>
+<dd><p>Used to enable and disable, respectively, the use of the integrated
+assembler. Whether the integrated assembler is on by default is target
+dependent.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-time">
+<tt class="descname">-time</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-time" title="Permalink to this definition">¶</a></dt>
+<dd><p>Time individual commands.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftime-report">
+<tt class="descname">-ftime-report</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ftime-report" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print timing summary of each stage of compilation.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-v">
+<tt class="descname">-v</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-v" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show commands to run and use verbose output.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="diagnostics-options">
+<h3>Diagnostics Options<a class="headerlink" href="#diagnostics-options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-fshow-column">
+<span id="cmdoption-fshow-source-location"></span><span id="cmdoption-fcaret-diagnostics"></span><span id="cmdoption-fdiagnostics-fixit-info"></span><span id="cmdoption-fdiagnostics-parseable-fixits"></span><span id="cmdoption-fdiagnostics-print-source-range-info"></span><span id="cmdoption-fprint-source-range-info"></span><span id="cmdoption-fdiagnostics-show-option"></span><span id="cmdoption-fmessage-length"></span><tt class="descname">-fshow-column</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-fshow-source-location</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-fcaret-diagnostics</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-fdiagnostics-fixit-info</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-fdiagnostics-parseable-fixits</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descna
 me">-fdiagnostics-print-source-range-info</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-fprint-source-range-info</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-fdiagnostics-show-option</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-fmessage-length</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fshow-column" title="Permalink to this definition">¶</a></dt>
+<dd><p>These options control how Clang prints out information about diagnostics
+(errors and warnings). Please see the Clang User’s Manual for more information.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="preprocessor-options">
+<h3>Preprocessor Options<a class="headerlink" href="#preprocessor-options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-D">
+<tt class="descname">-D</tt><tt class="descclassname"><macroname>=<value></tt><a class="headerlink" href="#cmdoption-D" title="Permalink to this definition">¶</a></dt>
+<dd><p>Adds an implicit #define into the predefines buffer which is read before the
+source file is preprocessed.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-U">
+<tt class="descname">-U</tt><tt class="descclassname"><macroname></tt><a class="headerlink" href="#cmdoption-U" title="Permalink to this definition">¶</a></dt>
+<dd><p>Adds an implicit #undef into the predefines buffer which is read before the
+source file is preprocessed.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-include">
+<tt class="descname">-include</tt><tt class="descclassname"> <filename></tt><a class="headerlink" href="#cmdoption-include" title="Permalink to this definition">¶</a></dt>
+<dd><p>Adds an implicit #include into the predefines buffer which is read before the
+source file is preprocessed.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-I">
+<tt class="descname">-I</tt><tt class="descclassname"><directory></tt><a class="headerlink" href="#cmdoption-I" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add the specified directory to the search path for include files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-F">
+<tt class="descname">-F</tt><tt class="descclassname"><directory></tt><a class="headerlink" href="#cmdoption-F" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add the specified directory to the search path for framework include files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-nostdinc">
+<tt class="descname">-nostdinc</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-nostdinc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not search the standard system directories or compiler builtin directories
+for include files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-nostdlibinc">
+<tt class="descname">-nostdlibinc</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-nostdlibinc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not search the standard system directories for include files, but do
+search compiler builtin include directories.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-nobuiltininc">
+<tt class="descname">-nobuiltininc</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-nobuiltininc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not search clang’s builtin directory for include files.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="environment">
+<h2>ENVIRONMENT<a class="headerlink" href="#environment" title="Permalink to this headline">¶</a></h2>
+<dl class="envvar">
+<dt id="envvar-TMPDIR,TEMP,TMP">
+<tt class="descname">TMPDIR, TEMP, TMP</tt><a class="headerlink" href="#envvar-TMPDIR,TEMP,TMP" title="Permalink to this definition">¶</a></dt>
+<dd><p>These environment variables are checked, in order, for the location to write
+temporary files used during the compilation process.</p>
+</dd></dl>
+
+<dl class="envvar">
+<dt id="envvar-CPATH">
+<tt class="descname">CPATH</tt><a class="headerlink" href="#envvar-CPATH" title="Permalink to this definition">¶</a></dt>
+<dd><p>If this environment variable is present, it is treated as a delimited list of
+paths to be added to the default system include path list. The delimiter is
+the platform dependent delimiter, as used in the PATH environment variable.</p>
+<p>Empty components in the environment variable are ignored.</p>
+</dd></dl>
+
+<dl class="envvar">
+<dt id="envvar-C_INCLUDE_PATH,OBJC_INCLUDE_PATH,CPLUS_INCLUDE_PATH,OBJCPLUS_INCLUDE_PATH">
+<tt class="descname">C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH</tt><a class="headerlink" href="#envvar-C_INCLUDE_PATH,OBJC_INCLUDE_PATH,CPLUS_INCLUDE_PATH,OBJCPLUS_INCLUDE_PATH" title="Permalink to this definition">¶</a></dt>
+<dd><p>These environment variables specify additional paths, as for <span class="target" id="index-0"></span><a class="reference internal" href="#envvar-CPATH"><tt class="xref std std-envvar docutils literal"><span class="pre">CPATH</span></tt></a>, which are
+only used when processing the appropriate language.</p>
+</dd></dl>
+
+<dl class="envvar">
+<dt id="envvar-MACOSX_DEPLOYMENT_TARGET">
+<tt class="descname">MACOSX_DEPLOYMENT_TARGET</tt><a class="headerlink" href="#envvar-MACOSX_DEPLOYMENT_TARGET" title="Permalink to this definition">¶</a></dt>
+<dd><p>If <a class="reference internal" href="#cmdoption-mmacosx-version-min"><em class="xref std std-option">-mmacosx-version-min</em></a> is unspecified, the default deployment
+target is read from this environment variable. This option only affects
+Darwin targets.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="bugs">
+<h2>BUGS<a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h2>
+<p>To report bugs, please visit <<a class="reference external" href="http://llvm.org/bugs/">http://llvm.org/bugs/</a>>.  Most bug reports should
+include preprocessed source files (use the <a class="reference internal" href="#cmdoption-E"><em class="xref std std-option">-E</em></a> option) and the full
+output of the compiler, along with information to reproduce.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><em class="manpage">as(1)</em>, <em class="manpage">ld(1)</em></p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="index.html">Clang “man” pages</a>
+          ::  
+        <a class="uplink" href="../index.html">Contents</a>
+          ::  
+        <a href="../FAQ.html">Frequently Asked Questions (FAQ)</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/CommandGuide/index.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/CommandGuide/index.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/CommandGuide/index.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/CommandGuide/index.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,87 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Clang “man” pages — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="../_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    '../',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="../_static/jquery.js"></script>
+    <script type="text/javascript" src="../_static/underscore.js"></script>
+    <script type="text/javascript" src="../_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="../index.html" />
+    <link rel="next" title="clang - the Clang C, C++, and Objective-C compiler" href="clang.html" />
+    <link rel="prev" title="ThinLTO" href="../ThinLTO.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="../index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Clang “man” pages</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="../ThinLTO.html">ThinLTO</a>
+          ::  
+        <a class="uplink" href="../index.html">Contents</a>
+          ::  
+        <a href="clang.html">clang - the Clang C, C++, and Objective-C compiler</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clang-man-pages">
+<h1>Clang “man” pages<a class="headerlink" href="#clang-man-pages" title="Permalink to this headline">¶</a></h1>
+<p>The following documents are command descriptions for all of the Clang tools.
+These pages describe how to use the Clang commands and what their options are.
+Note that these pages do not describe all of the options available for all
+tools. To get a complete listing, pass the <tt class="docutils literal"><span class="pre">--help</span></tt> (general options) or
+<tt class="docutils literal"><span class="pre">--help-hidden</span></tt> (general and debugging options) arguments to the tool you are
+interested in.</p>
+<div class="section" id="basic-commands">
+<h2>Basic Commands<a class="headerlink" href="#basic-commands" title="Permalink to this headline">¶</a></h2>
+<div class="toctree-wrapper compound">
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="clang.html">clang - the Clang C, C++, and Objective-C compiler</a></li>
+</ul>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="../ThinLTO.html">ThinLTO</a>
+          ::  
+        <a class="uplink" href="../index.html">Contents</a>
+          ::  
+        <a href="clang.html">clang - the Clang C, C++, and Objective-C compiler</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/ControlFlowIntegrity.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ControlFlowIntegrity.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ControlFlowIntegrity.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ControlFlowIntegrity.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,322 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Control Flow Integrity — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="next" title="Control Flow Integrity Design Documentation" href="ControlFlowIntegrityDesign.html" />
+    <link rel="prev" title="Sanitizer special case list" href="SanitizerSpecialCaseList.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Control Flow Integrity</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="SanitizerSpecialCaseList.html">Sanitizer special case list</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ControlFlowIntegrityDesign.html">Control Flow Integrity Design Documentation</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="control-flow-integrity">
+<h1>Control Flow Integrity<a class="headerlink" href="#control-flow-integrity" title="Permalink to this headline">¶</a></h1>
+<div class="toctree-wrapper compound">
+</div>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#available-schemes" id="id2">Available schemes</a></li>
+<li><a class="reference internal" href="#trapping-and-diagnostics" id="id3">Trapping and Diagnostics</a></li>
+<li><a class="reference internal" href="#forward-edge-cfi-for-virtual-calls" id="id4">Forward-Edge CFI for Virtual Calls</a><ul>
+<li><a class="reference internal" href="#performance" id="id5">Performance</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#bad-cast-checking" id="id6">Bad Cast Checking</a></li>
+<li><a class="reference internal" href="#non-virtual-member-function-call-checking" id="id7">Non-Virtual Member Function Call Checking</a><ul>
+<li><a class="reference internal" href="#strictness" id="id8">Strictness</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#indirect-function-call-checking" id="id9">Indirect Function Call Checking</a><ul>
+<li><a class="reference internal" href="#fsanitize-cfi-icall-and-fsanitize-function" id="id10"><tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt> and <tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#blacklist" id="id11">Blacklist</a></li>
+<li><a class="reference internal" href="#shared-library-support" id="id12">Shared library support</a></li>
+<li><a class="reference internal" href="#design" id="id13">Design</a></li>
+<li><a class="reference internal" href="#publications" id="id14">Publications</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Clang includes an implementation of a number of control flow integrity (CFI)
+schemes, which are designed to abort the program upon detecting certain forms
+of undefined behavior that can potentially allow attackers to subvert the
+program’s control flow. These schemes have been optimized for performance,
+allowing developers to enable them in release builds.</p>
+<p>To enable Clang’s available CFI schemes, use the flag <tt class="docutils literal"><span class="pre">-fsanitize=cfi</span></tt>.
+You can also enable a subset of available <a class="reference internal" href="#cfi-schemes"><em>schemes</em></a>.
+As currently implemented, all schemes rely on link-time optimization (LTO);
+so it is required to specify <tt class="docutils literal"><span class="pre">-flto</span></tt>, and the linker used must support LTO,
+for example via the <a class="reference external" href="http://llvm.org/docs/GoldPlugin.html">gold plugin</a>.</p>
+<p>To allow the checks to be implemented efficiently, the program must
+be structured such that certain object files are compiled with CFI
+enabled, and are statically linked into the program. This may preclude
+the use of shared libraries in some cases.</p>
+<p>The compiler will only produce CFI checks for a class if it can infer hidden
+LTO visibility for that class. LTO visibility is a property of a class that
+is inferred from flags and attributes. For more details, see the documentation
+for <a class="reference internal" href="LTOVisibility.html"><em>LTO visibility</em></a>.</p>
+<p>The <tt class="docutils literal"><span class="pre">-fsanitize=cfi-{vcall,nvcall,derived-cast,unrelated-cast}</span></tt> flags
+require that a <tt class="docutils literal"><span class="pre">-fvisibility=</span></tt> flag also be specified. This is because the
+default visibility setting is <tt class="docutils literal"><span class="pre">-fvisibility=default</span></tt>, which would disable
+CFI checks for classes without visibility attributes. Most users will want
+to specify <tt class="docutils literal"><span class="pre">-fvisibility=hidden</span></tt>, which enables CFI checks for such classes.</p>
+<p>Experimental support for <a class="reference internal" href="#cfi-cross-dso"><em>cross-DSO control flow integrity</em></a> exists that does not require classes to have hidden LTO
+visibility. This cross-DSO support has unstable ABI at this time.</p>
+</div>
+<div class="section" id="available-schemes">
+<span id="cfi-schemes"></span><h2><a class="toc-backref" href="#id2">Available schemes</a><a class="headerlink" href="#available-schemes" title="Permalink to this headline">¶</a></h2>
+<p>Available schemes are:</p>
+<blockquote>
+<div><ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-cast-strict</span></tt>: Enables <a class="reference internal" href="#cfi-strictness"><em>strict cast checks</em></a>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-derived-cast</span></tt>: Base-to-derived cast to the wrong
+dynamic type.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-unrelated-cast</span></tt>: Cast from <tt class="docutils literal"><span class="pre">void*</span></tt> or another
+unrelated type to the wrong dynamic type.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-nvcall</span></tt>: Non-virtual call via an object whose vptr is of
+the wrong dynamic type.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-vcall</span></tt>: Virtual call via an object whose vptr is of the
+wrong dynamic type.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt>: Indirect call of a function with wrong dynamic
+type.</li>
+</ul>
+</div></blockquote>
+<p>You can use <tt class="docutils literal"><span class="pre">-fsanitize=cfi</span></tt> to enable all the schemes and use
+<tt class="docutils literal"><span class="pre">-fno-sanitize</span></tt> flag to narrow down the set of schemes as desired.
+For example, you can build your program with
+<tt class="docutils literal"><span class="pre">-fsanitize=cfi</span> <span class="pre">-fno-sanitize=cfi-nvcall,cfi-icall</span></tt>
+to use all schemes except for non-virtual member function call and indirect call
+checking.</p>
+<p>Remember that you have to provide <tt class="docutils literal"><span class="pre">-flto</span></tt> if at least one CFI scheme is
+enabled.</p>
+</div>
+<div class="section" id="trapping-and-diagnostics">
+<h2><a class="toc-backref" href="#id3">Trapping and Diagnostics</a><a class="headerlink" href="#trapping-and-diagnostics" title="Permalink to this headline">¶</a></h2>
+<p>By default, CFI will abort the program immediately upon detecting a control
+flow integrity violation. You can use the <a class="reference internal" href="UsersManual.html#controlling-code-generation"><em>-fno-sanitize-trap=</em></a> flag to cause CFI to print a diagnostic
+similar to the one below before the program aborts.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">bad-cast.cpp:109:7: runtime error: control flow integrity check for type 'B' failed during base-to-derived cast (vtable address 0x000000425a50)</span>
+<span class="go">0x000000425a50: note: vtable is of type 'A'</span>
+<span class="go"> 00 00 00 00  f0 f1 41 00 00 00 00 00  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  20 5a 42 00</span>
+<span class="go">              ^</span>
+</pre></div>
+</div>
+<p>If diagnostics are enabled, you can also configure CFI to continue program
+execution instead of aborting by using the <a class="reference internal" href="UsersManual.html#controlling-code-generation"><em>-fsanitize-recover=</em></a> flag.</p>
+</div>
+<div class="section" id="forward-edge-cfi-for-virtual-calls">
+<h2><a class="toc-backref" href="#id4">Forward-Edge CFI for Virtual Calls</a><a class="headerlink" href="#forward-edge-cfi-for-virtual-calls" title="Permalink to this headline">¶</a></h2>
+<p>This scheme checks that virtual calls take place using a vptr of the correct
+dynamic type; that is, the dynamic type of the called object must be a
+derived class of the static type of the object used to make the call.
+This CFI scheme can be enabled on its own using <tt class="docutils literal"><span class="pre">-fsanitize=cfi-vcall</span></tt>.</p>
+<p>For this scheme to work, all translation units containing the definition
+of a virtual member function (whether inline or not), other than members
+of <a class="reference internal" href="#cfi-blacklist"><em>blacklisted</em></a> types, must be compiled with
+<tt class="docutils literal"><span class="pre">-fsanitize=cfi-vcall</span></tt> enabled and be statically linked into the program.</p>
+<div class="section" id="performance">
+<h3><a class="toc-backref" href="#id5">Performance</a><a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h3>
+<p>A performance overhead of less than 1% has been measured by running the
+Dromaeo benchmark suite against an instrumented version of the Chromium
+web browser. Another good performance benchmark for this mechanism is the
+virtual-call-heavy SPEC 2006 xalancbmk.</p>
+<p>Note that this scheme has not yet been optimized for binary size; an increase
+of up to 15% has been observed for Chromium.</p>
+</div>
+</div>
+<div class="section" id="bad-cast-checking">
+<h2><a class="toc-backref" href="#id6">Bad Cast Checking</a><a class="headerlink" href="#bad-cast-checking" title="Permalink to this headline">¶</a></h2>
+<p>This scheme checks that pointer casts are made to an object of the correct
+dynamic type; that is, the dynamic type of the object must be a derived class
+of the pointee type of the cast. The checks are currently only introduced
+where the class being casted to is a polymorphic class.</p>
+<p>Bad casts are not in themselves control flow integrity violations, but they
+can also create security vulnerabilities, and the implementation uses many
+of the same mechanisms.</p>
+<p>There are two types of bad cast that may be forbidden: bad casts
+from a base class to a derived class (which can be checked with
+<tt class="docutils literal"><span class="pre">-fsanitize=cfi-derived-cast</span></tt>), and bad casts from a pointer of
+type <tt class="docutils literal"><span class="pre">void*</span></tt> or another unrelated type (which can be checked with
+<tt class="docutils literal"><span class="pre">-fsanitize=cfi-unrelated-cast</span></tt>).</p>
+<p>The difference between these two types of casts is that the first is defined
+by the C++ standard to produce an undefined value, while the second is not
+in itself undefined behavior (it is well defined to cast the pointer back
+to its original type) unless the object is uninitialized and the cast is a
+<tt class="docutils literal"><span class="pre">static_cast</span></tt> (see C++14 [basic.life]p5).</p>
+<p>If a program as a matter of policy forbids the second type of cast, that
+restriction can normally be enforced. However it may in some cases be necessary
+for a function to perform a forbidden cast to conform with an external API
+(e.g. the <tt class="docutils literal"><span class="pre">allocate</span></tt> member function of a standard library allocator). Such
+functions may be <a class="reference internal" href="#cfi-blacklist"><em>blacklisted</em></a>.</p>
+<p>For this scheme to work, all translation units containing the definition
+of a virtual member function (whether inline or not), other than members
+of <a class="reference internal" href="#cfi-blacklist"><em>blacklisted</em></a> types, must be compiled with
+<tt class="docutils literal"><span class="pre">-fsanitize=cfi-derived-cast</span></tt> or <tt class="docutils literal"><span class="pre">-fsanitize=cfi-unrelated-cast</span></tt> enabled
+and be statically linked into the program.</p>
+</div>
+<div class="section" id="non-virtual-member-function-call-checking">
+<h2><a class="toc-backref" href="#id7">Non-Virtual Member Function Call Checking</a><a class="headerlink" href="#non-virtual-member-function-call-checking" title="Permalink to this headline">¶</a></h2>
+<p>This scheme checks that non-virtual calls take place using an object of
+the correct dynamic type; that is, the dynamic type of the called object
+must be a derived class of the static type of the object used to make the
+call. The checks are currently only introduced where the object is of a
+polymorphic class type.  This CFI scheme can be enabled on its own using
+<tt class="docutils literal"><span class="pre">-fsanitize=cfi-nvcall</span></tt>.</p>
+<p>For this scheme to work, all translation units containing the definition
+of a virtual member function (whether inline or not), other than members
+of <a class="reference internal" href="#cfi-blacklist"><em>blacklisted</em></a> types, must be compiled with
+<tt class="docutils literal"><span class="pre">-fsanitize=cfi-nvcall</span></tt> enabled and be statically linked into the program.</p>
+<div class="section" id="strictness">
+<span id="cfi-strictness"></span><h3><a class="toc-backref" href="#id8">Strictness</a><a class="headerlink" href="#strictness" title="Permalink to this headline">¶</a></h3>
+<p>If a class has a single non-virtual base and does not introduce or override
+virtual member functions or fields other than an implicitly defined virtual
+destructor, it will have the same layout and virtual function semantics as
+its base. By default, casts to such classes are checked as if they were made
+to the least derived such class.</p>
+<p>Casting an instance of a base class to such a derived class is technically
+undefined behavior, but it is a relatively common hack for introducing
+member functions on class instances with specific properties that works under
+most compilers and should not have security implications, so we allow it by
+default. It can be disabled with <tt class="docutils literal"><span class="pre">-fsanitize=cfi-cast-strict</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="indirect-function-call-checking">
+<h2><a class="toc-backref" href="#id9">Indirect Function Call Checking</a><a class="headerlink" href="#indirect-function-call-checking" title="Permalink to this headline">¶</a></h2>
+<p>This scheme checks that function calls take place using a function of the
+correct dynamic type; that is, the dynamic type of the function must match
+the static type used at the call. This CFI scheme can be enabled on its own
+using <tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt>.</p>
+<p>For this scheme to work, each indirect function call in the program, other
+than calls in <a class="reference internal" href="#cfi-blacklist"><em>blacklisted</em></a> functions, must call a
+function which was either compiled with <tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt> enabled,
+or whose address was taken by a function in a translation unit compiled with
+<tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt>.</p>
+<p>If a function in a translation unit compiled with <tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt>
+takes the address of a function not compiled with <tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt>,
+that address may differ from the address taken by a function in a translation
+unit not compiled with <tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt>. This is technically a
+violation of the C and C++ standards, but it should not affect most programs.</p>
+<p>Each translation unit compiled with <tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt> must be
+statically linked into the program or shared library, and calls across
+shared library boundaries are handled as if the callee was not compiled with
+<tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt>.</p>
+<p>This scheme is currently only supported on the x86 and x86_64 architectures.</p>
+<div class="section" id="fsanitize-cfi-icall-and-fsanitize-function">
+<h3><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt> and <tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt></a><a class="headerlink" href="#fsanitize-cfi-icall-and-fsanitize-function" title="Permalink to this headline">¶</a></h3>
+<p>This tool is similar to <tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt> in that both tools check
+the types of function calls. However, the two tools occupy different points
+on the design space; <tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt> is a developer tool designed
+to find bugs in local development builds, whereas <tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt>
+is a security hardening mechanism designed to be deployed in release builds.</p>
+<p><tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt> has a higher space and time overhead due to a more
+complex type check at indirect call sites, as well as a need for run-time
+type information (RTTI), which may make it unsuitable for deployment. Because
+of the need for RTTI, <tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt> can only be used with C++
+programs, whereas <tt class="docutils literal"><span class="pre">-fsanitize=cfi-icall</span></tt> can protect both C and C++ programs.</p>
+<p>On the other hand, <tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt> conforms more closely with the C++
+standard and user expectations around interaction with shared libraries;
+the identity of function pointers is maintained, and calls across shared
+library boundaries are no different from calls within a single program or
+shared library.</p>
+</div>
+</div>
+<div class="section" id="blacklist">
+<span id="cfi-blacklist"></span><h2><a class="toc-backref" href="#id11">Blacklist</a><a class="headerlink" href="#blacklist" title="Permalink to this headline">¶</a></h2>
+<p>A <a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a> can be used to relax CFI checks for certain
+source files, functions and types using the <tt class="docutils literal"><span class="pre">src</span></tt>, <tt class="docutils literal"><span class="pre">fun</span></tt> and <tt class="docutils literal"><span class="pre">type</span></tt>
+entity types.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Suppress checking for code in a file.</span>
+src:bad_file.cpp
+src:bad_header.h
+<span class="c"># Ignore all functions with names containing MyFooBar.</span>
+fun:*MyFooBar*
+<span class="c"># Ignore all types in the standard library.</span>
+<span class="nb">type</span>:std::*
+</pre></div>
+</div>
+</div>
+<div class="section" id="shared-library-support">
+<span id="cfi-cross-dso"></span><h2><a class="toc-backref" href="#id12">Shared library support</a><a class="headerlink" href="#shared-library-support" title="Permalink to this headline">¶</a></h2>
+<p>Use <strong>-f[no-]sanitize-cfi-cross-dso</strong> to enable the cross-DSO control
+flow integrity mode, which allows all CFI schemes listed above to
+apply across DSO boundaries. As in the regular CFI, each DSO must be
+built with <tt class="docutils literal"><span class="pre">-flto</span></tt>.</p>
+<p>Normally, CFI checks will only be performed for classes that have hidden LTO
+visibility. With this flag enabled, the compiler will emit cross-DSO CFI
+checks for all classes, except for those which appear in the CFI blacklist
+or which use a <tt class="docutils literal"><span class="pre">no_sanitize</span></tt> attribute.</p>
+</div>
+<div class="section" id="design">
+<h2><a class="toc-backref" href="#id13">Design</a><a class="headerlink" href="#design" title="Permalink to this headline">¶</a></h2>
+<p>Please refer to the <a class="reference internal" href="ControlFlowIntegrityDesign.html"><em>design document</em></a>.</p>
+</div>
+<div class="section" id="publications">
+<h2><a class="toc-backref" href="#id14">Publications</a><a class="headerlink" href="#publications" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="http://research.microsoft.com/pubs/64250/ccs05.pdf">Control-Flow Integrity: Principles, Implementations, and Applications</a>.
+Martin Abadi, Mihai Budiu, Úlfar Erlingsson, Jay Ligatti.</p>
+<p><a class="reference external" href="http://www.pcc.me.uk/~peter/acad/usenix14.pdf">Enforcing Forward-Edge Control-Flow Integrity in GCC & LLVM</a>.
+Caroline Tice, Tom Roeder, Peter Collingbourne, Stephen Checkoway,
+Úlfar Erlingsson, Luis Lozano, Geoff Pike.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="SanitizerSpecialCaseList.html">Sanitizer special case list</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ControlFlowIntegrityDesign.html">Control Flow Integrity Design Documentation</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/ControlFlowIntegrityDesign.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/ControlFlowIntegrityDesign.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/ControlFlowIntegrityDesign.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/ControlFlowIntegrityDesign.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,868 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Control Flow Integrity Design Documentation — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="up" title="Control Flow Integrity" href="ControlFlowIntegrity.html" />
+    <link rel="next" title="LTO Visibility" href="LTOVisibility.html" />
+    <link rel="prev" title="Control Flow Integrity" href="ControlFlowIntegrity.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Control Flow Integrity Design Documentation</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="ControlFlowIntegrity.html">Control Flow Integrity</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LTOVisibility.html">LTO Visibility</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="control-flow-integrity-design-documentation">
+<h1>Control Flow Integrity Design Documentation<a class="headerlink" href="#control-flow-integrity-design-documentation" title="Permalink to this headline">¶</a></h1>
+<p>This page documents the design of the <a class="reference internal" href="ControlFlowIntegrity.html"><em>Control Flow Integrity</em></a> schemes
+supported by Clang.</p>
+<div class="section" id="forward-edge-cfi-for-virtual-calls">
+<h2>Forward-Edge CFI for Virtual Calls<a class="headerlink" href="#forward-edge-cfi-for-virtual-calls" title="Permalink to this headline">¶</a></h2>
+<p>This scheme works by allocating, for each static type used to make a virtual
+call, a region of read-only storage in the object file holding a bit vector
+that maps onto to the region of storage used for those virtual tables. Each
+set bit in the bit vector corresponds to the <a class="reference external" href="https://mentorembedded.github.io/cxx-abi/abi.html#vtable-general">address point</a> for a virtual
+table compatible with the static type for which the bit vector is being built.</p>
+<p>For example, consider the following three C++ classes:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">A</span> <span class="p">{</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="n">f1</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f2</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f3</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">B</span> <span class="o">:</span> <span class="n">A</span> <span class="p">{</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="n">f1</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f2</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f3</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">C</span> <span class="o">:</span> <span class="n">A</span> <span class="p">{</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="n">f1</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f2</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f3</span><span class="p">();</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The scheme will cause the virtual tables for A, B and C to be laid out
+consecutively:</p>
+<table border="1" class="docutils">
+<caption>Virtual Table Layout for A, B, C</caption>
+<colgroup>
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+<col width="7%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">0</th>
+<th class="head">1</th>
+<th class="head">2</th>
+<th class="head">3</th>
+<th class="head">4</th>
+<th class="head">5</th>
+<th class="head">6</th>
+<th class="head">7</th>
+<th class="head">8</th>
+<th class="head">9</th>
+<th class="head">10</th>
+<th class="head">11</th>
+<th class="head">12</th>
+<th class="head">13</th>
+<th class="head">14</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>A::offset-to-top</td>
+<td>&A::rtti</td>
+<td>&A::f1</td>
+<td>&A::f2</td>
+<td>&A::f3</td>
+<td>B::offset-to-top</td>
+<td>&B::rtti</td>
+<td>&B::f1</td>
+<td>&B::f2</td>
+<td>&B::f3</td>
+<td>C::offset-to-top</td>
+<td>&C::rtti</td>
+<td>&C::f1</td>
+<td>&C::f2</td>
+<td>&C::f3</td>
+</tr>
+</tbody>
+</table>
+<p>The bit vector for static types A, B and C will look like this:</p>
+<table border="1" class="docutils">
+<caption>Bit Vectors for A, B, C</caption>
+<colgroup>
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Class</th>
+<th class="head">0</th>
+<th class="head">1</th>
+<th class="head">2</th>
+<th class="head">3</th>
+<th class="head">4</th>
+<th class="head">5</th>
+<th class="head">6</th>
+<th class="head">7</th>
+<th class="head">8</th>
+<th class="head">9</th>
+<th class="head">10</th>
+<th class="head">11</th>
+<th class="head">12</th>
+<th class="head">13</th>
+<th class="head">14</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>A</td>
+<td>0</td>
+<td>0</td>
+<td>1</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>1</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>1</td>
+<td>0</td>
+<td>0</td>
+</tr>
+<tr class="row-odd"><td>B</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>1</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+</tr>
+<tr class="row-even"><td>C</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>1</td>
+<td>0</td>
+<td>0</td>
+</tr>
+</tbody>
+</table>
+<p>Bit vectors are represented in the object file as byte arrays. By loading
+from indexed offsets into the byte array and applying a mask, a program can
+test bits from the bit set with a relatively short instruction sequence. Bit
+vectors may overlap so long as they use different bits. For the full details,
+see the <a class="reference external" href="http://llvm.org/docs/doxygen/html/structllvm_1_1ByteArrayBuilder.html">ByteArrayBuilder</a> class.</p>
+<p>In this case, assuming A is laid out at offset 0 in bit 0, B at offset 0 in
+bit 1 and C at offset 0 in bit 2, the byte array would look like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">char</span> <span class="n">bits</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span> <span class="p">};</span>
+</pre></div>
+</div>
+<p>To emit a virtual call, the compiler will assemble code that checks that
+the object’s virtual table pointer is in-bounds and aligned and that the
+relevant bit is set in the bit vector.</p>
+<p>For example on x86 a typical virtual call may look like this:</p>
+<div class="highlight-none"><div class="highlight"><pre>ca7fbb:       48 8b 0f                mov    (%rdi),%rcx
+ca7fbe:       48 8d 15 c3 42 fb 07    lea    0x7fb42c3(%rip),%rdx
+ca7fc5:       48 89 c8                mov    %rcx,%rax
+ca7fc8:       48 29 d0                sub    %rdx,%rax
+ca7fcb:       48 c1 c0 3d             rol    $0x3d,%rax
+ca7fcf:       48 3d 7f 01 00 00       cmp    $0x17f,%rax
+ca7fd5:       0f 87 36 05 00 00       ja     ca8511
+ca7fdb:       48 8d 15 c0 0b f7 06    lea    0x6f70bc0(%rip),%rdx
+ca7fe2:       f6 04 10 10             testb  $0x10,(%rax,%rdx,1)
+ca7fe6:       0f 84 25 05 00 00       je     ca8511
+ca7fec:       ff 91 98 00 00 00       callq  *0x98(%rcx)
+  [...]
+ca8511:       0f 0b                   ud2
+</pre></div>
+</div>
+<p>The compiler relies on co-operation from the linker in order to assemble
+the bit vectors for the whole program. It currently does this using LLVM’s
+<a class="reference external" href="http://llvm.org/docs/TypeMetadata.html">type metadata</a> mechanism together with link-time optimization.</p>
+<div class="section" id="optimizations">
+<h3>Optimizations<a class="headerlink" href="#optimizations" title="Permalink to this headline">¶</a></h3>
+<p>The scheme as described above is the fully general variant of the scheme.
+Most of the time we are able to apply one or more of the following
+optimizations to improve binary size or performance.</p>
+<p>In fact, if you try the above example with the current version of the
+compiler, you will probably find that it will not use the described virtual
+table layout or machine instructions. Some of the optimizations we are about
+to introduce cause the compiler to use a different layout or a different
+sequence of machine instructions.</p>
+<div class="section" id="stripping-leading-trailing-zeros-in-bit-vectors">
+<h4>Stripping Leading/Trailing Zeros in Bit Vectors<a class="headerlink" href="#stripping-leading-trailing-zeros-in-bit-vectors" title="Permalink to this headline">¶</a></h4>
+<p>If a bit vector contains leading or trailing zeros, we can strip them from
+the vector. The compiler will emit code to check if the pointer is in range
+of the region covered by ones, and perform the bit vector check using a
+truncated version of the bit vector. For example, the bit vectors for our
+example class hierarchy will be emitted like this:</p>
+<table border="1" class="docutils">
+<caption>Bit Vectors for A, B, C</caption>
+<colgroup>
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Class</th>
+<th class="head">0</th>
+<th class="head">1</th>
+<th class="head">2</th>
+<th class="head">3</th>
+<th class="head">4</th>
+<th class="head">5</th>
+<th class="head">6</th>
+<th class="head">7</th>
+<th class="head">8</th>
+<th class="head">9</th>
+<th class="head">10</th>
+<th class="head">11</th>
+<th class="head">12</th>
+<th class="head">13</th>
+<th class="head">14</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>A</td>
+<td> </td>
+<td> </td>
+<td>1</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>1</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>0</td>
+<td>1</td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-odd"><td>B</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>1</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td>C</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>1</td>
+<td> </td>
+<td> </td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="short-inline-bit-vectors">
+<h4>Short Inline Bit Vectors<a class="headerlink" href="#short-inline-bit-vectors" title="Permalink to this headline">¶</a></h4>
+<p>If the vector is sufficiently short, we can represent it as an inline constant
+on x86. This saves us a few instructions when reading the correct element
+of the bit vector.</p>
+<p>If the bit vector fits in 32 bits, the code looks like this:</p>
+<div class="highlight-none"><div class="highlight"><pre> dc2:       48 8b 03                mov    (%rbx),%rax
+ dc5:       48 8d 15 14 1e 00 00    lea    0x1e14(%rip),%rdx
+ dcc:       48 89 c1                mov    %rax,%rcx
+ dcf:       48 29 d1                sub    %rdx,%rcx
+ dd2:       48 c1 c1 3d             rol    $0x3d,%rcx
+ dd6:       48 83 f9 03             cmp    $0x3,%rcx
+ dda:       77 2f                   ja     e0b <main+0x9b>
+ ddc:       ba 09 00 00 00          mov    $0x9,%edx
+ de1:       0f a3 ca                bt     %ecx,%edx
+ de4:       73 25                   jae    e0b <main+0x9b>
+ de6:       48 89 df                mov    %rbx,%rdi
+ de9:       ff 10                   callq  *(%rax)
+[...]
+ e0b:       0f 0b                   ud2
+</pre></div>
+</div>
+<p>Or if the bit vector fits in 64 bits:</p>
+<div class="highlight-none"><div class="highlight"><pre>11a6:       48 8b 03                mov    (%rbx),%rax
+11a9:       48 8d 15 d0 28 00 00    lea    0x28d0(%rip),%rdx
+11b0:       48 89 c1                mov    %rax,%rcx
+11b3:       48 29 d1                sub    %rdx,%rcx
+11b6:       48 c1 c1 3d             rol    $0x3d,%rcx
+11ba:       48 83 f9 2a             cmp    $0x2a,%rcx
+11be:       77 35                   ja     11f5 <main+0xb5>
+11c0:       48 ba 09 00 00 00 00    movabs $0x40000000009,%rdx
+11c7:       04 00 00
+11ca:       48 0f a3 ca             bt     %rcx,%rdx
+11ce:       73 25                   jae    11f5 <main+0xb5>
+11d0:       48 89 df                mov    %rbx,%rdi
+11d3:       ff 10                   callq  *(%rax)
+[...]
+11f5:       0f 0b                   ud2
+</pre></div>
+</div>
+<p>If the bit vector consists of a single bit, there is only one possible
+virtual table, and the check can consist of a single equality comparison:</p>
+<div class="highlight-none"><div class="highlight"><pre>9a2:   48 8b 03                mov    (%rbx),%rax
+9a5:   48 8d 0d a4 13 00 00    lea    0x13a4(%rip),%rcx
+9ac:   48 39 c8                cmp    %rcx,%rax
+9af:   75 25                   jne    9d6 <main+0x86>
+9b1:   48 89 df                mov    %rbx,%rdi
+9b4:   ff 10                   callq  *(%rax)
+[...]
+9d6:   0f 0b                   ud2
+</pre></div>
+</div>
+</div>
+<div class="section" id="virtual-table-layout">
+<h4>Virtual Table Layout<a class="headerlink" href="#virtual-table-layout" title="Permalink to this headline">¶</a></h4>
+<p>The compiler lays out classes of disjoint hierarchies in separate regions
+of the object file. At worst, bit vectors in disjoint hierarchies only
+need to cover their disjoint hierarchy. But the closer that classes in
+sub-hierarchies are laid out to each other, the smaller the bit vectors for
+those sub-hierarchies need to be (see “Stripping Leading/Trailing Zeros in Bit
+Vectors” above). The <a class="reference external" href="http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Transforms/IPO/LowerTypeTests.h?view=markup">GlobalLayoutBuilder</a> class is responsible for laying
+out the globals efficiently to minimize the sizes of the underlying bitsets.</p>
+</div>
+<div class="section" id="alignment">
+<h4>Alignment<a class="headerlink" href="#alignment" title="Permalink to this headline">¶</a></h4>
+<p>If all gaps between address points in a particular bit vector are multiples
+of powers of 2, the compiler can compress the bit vector by strengthening
+the alignment requirements of the virtual table pointer. For example, given
+this class hierarchy:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">A</span> <span class="p">{</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="n">f1</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f2</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">B</span> <span class="o">:</span> <span class="n">A</span> <span class="p">{</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="n">f1</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f2</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f3</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f4</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f5</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f6</span><span class="p">();</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">C</span> <span class="o">:</span> <span class="n">A</span> <span class="p">{</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="n">f1</span><span class="p">();</span>
+  <span class="k">virtual</span> <span class="kt">void</span> <span class="nf">f2</span><span class="p">();</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The virtual tables will be laid out like this:</p>
+<table border="1" class="docutils">
+<caption>Virtual Table Layout for A, B, C</caption>
+<colgroup>
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+<col width="6%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">0</th>
+<th class="head">1</th>
+<th class="head">2</th>
+<th class="head">3</th>
+<th class="head">4</th>
+<th class="head">5</th>
+<th class="head">6</th>
+<th class="head">7</th>
+<th class="head">8</th>
+<th class="head">9</th>
+<th class="head">10</th>
+<th class="head">11</th>
+<th class="head">12</th>
+<th class="head">13</th>
+<th class="head">14</th>
+<th class="head">15</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>A::offset-to-top</td>
+<td>&A::rtti</td>
+<td>&A::f1</td>
+<td>&A::f2</td>
+<td>B::offset-to-top</td>
+<td>&B::rtti</td>
+<td>&B::f1</td>
+<td>&B::f2</td>
+<td>&B::f3</td>
+<td>&B::f4</td>
+<td>&B::f5</td>
+<td>&B::f6</td>
+<td>C::offset-to-top</td>
+<td>&C::rtti</td>
+<td>&C::f1</td>
+<td>&C::f2</td>
+</tr>
+</tbody>
+</table>
+<p>Notice that each address point for A is separated by 4 words. This lets us
+emit a compressed bit vector for A that looks like this:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">2</th>
+<th class="head">6</th>
+<th class="head">10</th>
+<th class="head">14</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>1</td>
+<td>1</td>
+<td>0</td>
+<td>1</td>
+</tr>
+</tbody>
+</table>
+<p>At call sites, the compiler will strengthen the alignment requirements by
+using a different rotate count. For example, on a 64-bit machine where the
+address points are 4-word aligned (as in A from our example), the <tt class="docutils literal"><span class="pre">rol</span></tt>
+instruction may look like this:</p>
+<div class="highlight-none"><div class="highlight"><pre>dd2:       48 c1 c1 3b             rol    $0x3b,%rcx
+</pre></div>
+</div>
+</div>
+<div class="section" id="padding-to-powers-of-2">
+<h4>Padding to Powers of 2<a class="headerlink" href="#padding-to-powers-of-2" title="Permalink to this headline">¶</a></h4>
+<p>Of course, this alignment scheme works best if the address points are
+in fact aligned correctly. To make this more likely to happen, we insert
+padding between virtual tables that in many cases aligns address points to
+a power of 2. Specifically, our padding aligns virtual tables to the next
+highest power of 2 bytes; because address points for specific base classes
+normally appear at fixed offsets within the virtual table, this normally
+has the effect of aligning the address points as well.</p>
+<p>This scheme introduces tradeoffs between decreased space overhead for
+instructions and bit vectors and increased overhead in the form of padding. We
+therefore limit the amount of padding so that we align to no more than 128
+bytes. This number was found experimentally to provide a good tradeoff.</p>
+</div>
+<div class="section" id="eliminating-bit-vector-checks-for-all-ones-bit-vectors">
+<h4>Eliminating Bit Vector Checks for All-Ones Bit Vectors<a class="headerlink" href="#eliminating-bit-vector-checks-for-all-ones-bit-vectors" title="Permalink to this headline">¶</a></h4>
+<p>If the bit vector is all ones, the bit vector check is redundant; we simply
+need to check that the address is in range and well aligned. This is more
+likely to occur if the virtual tables are padded.</p>
+</div>
+</div>
+</div>
+<div class="section" id="forward-edge-cfi-for-indirect-function-calls">
+<h2>Forward-Edge CFI for Indirect Function Calls<a class="headerlink" href="#forward-edge-cfi-for-indirect-function-calls" title="Permalink to this headline">¶</a></h2>
+<p>Under forward-edge CFI for indirect function calls, each unique function
+type has its own bit vector, and at each call site we need to check that the
+function pointer is a member of the function type’s bit vector. This scheme
+works in a similar way to forward-edge CFI for virtual calls, the distinction
+being that we need to build bit vectors of function entry points rather than
+of virtual tables.</p>
+<p>Unlike when re-arranging global variables, we cannot re-arrange functions
+in a particular order and base our calculations on the layout of the
+functions’ entry points, as we have no idea how large a particular function
+will end up being (the function sizes could even depend on how we arrange
+the functions). Instead, we build a jump table, which is a block of code
+consisting of one branch instruction for each of the functions in the bit
+set that branches to the target function, and redirect any taken function
+addresses to the corresponding jump table entry. In this way, the distance
+between function entry points is predictable and controllable. In the object
+file’s symbol table, the symbols for the target functions also refer to the
+jump table entries, so that addresses taken outside the module will pass
+any verification done inside the module.</p>
+<p>In more concrete terms, suppose we have three functions <tt class="docutils literal"><span class="pre">f</span></tt>, <tt class="docutils literal"><span class="pre">g</span></tt>,
+<tt class="docutils literal"><span class="pre">h</span></tt> which are all of the same type, and a function foo that returns their
+addresses:</p>
+<div class="highlight-none"><div class="highlight"><pre>f:
+mov 0, %eax
+ret
+
+g:
+mov 1, %eax
+ret
+
+h:
+mov 2, %eax
+ret
+
+foo:
+mov f, %eax
+mov g, %edx
+mov h, %ecx
+ret
+</pre></div>
+</div>
+<p>Our jump table will (conceptually) look like this:</p>
+<div class="highlight-none"><div class="highlight"><pre>f:
+jmp .Ltmp0 ; 5 bytes
+int3       ; 1 byte
+int3       ; 1 byte
+int3       ; 1 byte
+
+g:
+jmp .Ltmp1 ; 5 bytes
+int3       ; 1 byte
+int3       ; 1 byte
+int3       ; 1 byte
+
+h:
+jmp .Ltmp2 ; 5 bytes
+int3       ; 1 byte
+int3       ; 1 byte
+int3       ; 1 byte
+
+.Ltmp0:
+mov 0, %eax
+ret
+
+.Ltmp1:
+mov 1, %eax
+ret
+
+.Ltmp2:
+mov 2, %eax
+ret
+
+foo:
+mov f, %eax
+mov g, %edx
+mov h, %ecx
+ret
+</pre></div>
+</div>
+<p>Because the addresses of <tt class="docutils literal"><span class="pre">f</span></tt>, <tt class="docutils literal"><span class="pre">g</span></tt>, <tt class="docutils literal"><span class="pre">h</span></tt> are evenly spaced at a power of
+2, and function types do not overlap (unlike class types with base classes),
+we can normally apply the <a class="reference internal" href="#alignment">Alignment</a> and <a class="reference internal" href="#eliminating-bit-vector-checks-for-all-ones-bit-vectors">Eliminating Bit Vector Checks
+for All-Ones Bit Vectors</a> optimizations thus simplifying the check at each
+call site to a range and alignment check.</p>
+</div>
+<div class="section" id="shared-library-support">
+<h2>Shared library support<a class="headerlink" href="#shared-library-support" title="Permalink to this headline">¶</a></h2>
+<p><strong>EXPERIMENTAL</strong></p>
+<p>The basic CFI mode described above assumes that the application is a
+monolithic binary; at least that all possible virtual/indirect call
+targets and the entire class hierarchy are known at link time. The
+cross-DSO mode, enabled with <strong>-f[no-]sanitize-cfi-cross-dso</strong> relaxes
+this requirement by allowing virtual and indirect calls to cross the
+DSO boundary.</p>
+<p>Assuming the following setup: the binary consists of several
+instrumented and several uninstrumented DSOs. Some of them may be
+dlopen-ed/dlclose-d periodically, even frequently.</p>
+<blockquote>
+<div><ul>
+<li><p class="first">Calls made from uninstrumented DSOs are not checked and just work.</p>
+</li>
+<li><p class="first">Calls inside any instrumented DSO are fully protected.</p>
+</li>
+<li><dl class="first docutils">
+<dt>Calls between different instrumented DSOs are also protected, with</dt>
+<dd><p class="first last">a performance penalty (in addition to the monolithic CFI
+overhead).</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt>Calls from an instrumented DSO to an uninstrumented one are</dt>
+<dd><p class="first last">unchecked and just work, with performance penalty.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt>Calls from an instrumented DSO outside of any known DSO are</dt>
+<dd><p class="first last">detected as CFI violations.</p>
+</dd>
+</dl>
+</li>
+</ul>
+</div></blockquote>
+<p>In the monolithic scheme a call site is instrumented as</p>
+<div class="highlight-none"><div class="highlight"><pre>if (!InlinedFastCheck(f))
+  abort();
+call *f
+</pre></div>
+</div>
+<p>In the cross-DSO scheme it becomes</p>
+<div class="highlight-none"><div class="highlight"><pre>if (!InlinedFastCheck(f))
+  __cfi_slowpath(CallSiteTypeId, f);
+call *f
+</pre></div>
+</div>
+<div class="section" id="callsitetypeid">
+<h3>CallSiteTypeId<a class="headerlink" href="#callsitetypeid" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">CallSiteTypeId</span></tt> is a stable process-wide identifier of the
+call-site type. For a virtual call site, the type in question is the class
+type; for an indirect function call it is the function signature. The
+mapping from a type to an identifier is an ABI detail. In the current,
+experimental, implementation the identifier of type T is calculated as
+follows:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Obtain the mangled name for “typeinfo name for T”.</li>
+<li>Calculate MD5 hash of the name as a string.</li>
+<li>Reinterpret the first 8 bytes of the hash as a little-endian
+64-bit integer.</li>
+</ul>
+</div></blockquote>
+<p>It is possible, but unlikely, that collisions in the
+<tt class="docutils literal"><span class="pre">CallSiteTypeId</span></tt> hashing will result in weaker CFI checks that would
+still be conservatively correct.</p>
+</div>
+<div class="section" id="cfi-check">
+<h3>CFI_Check<a class="headerlink" href="#cfi-check" title="Permalink to this headline">¶</a></h3>
+<p>In the general case, only the target DSO knows whether the call to
+function <tt class="docutils literal"><span class="pre">f</span></tt> with type <tt class="docutils literal"><span class="pre">CallSiteTypeId</span></tt> is valid or not.  To
+export this information, every DSO implements</p>
+<div class="highlight-none"><div class="highlight"><pre>void __cfi_check(uint64 CallSiteTypeId, void *TargetAddr)
+</pre></div>
+</div>
+<p>This function provides external modules with access to CFI checks for the
+targets inside this DSO.  For each known <tt class="docutils literal"><span class="pre">CallSiteTypeId</span></tt>, this function
+performs an <tt class="docutils literal"><span class="pre">llvm.type.test</span></tt> with the corresponding type identifier. It
+aborts if the type is unknown, or if the check fails.</p>
+<p>The basic implementation is a large switch statement over all values
+of CallSiteTypeId supported by this DSO, and each case is similar to
+the InlinedFastCheck() in the basic CFI mode.</p>
+</div>
+<div class="section" id="cfi-shadow">
+<h3>CFI Shadow<a class="headerlink" href="#cfi-shadow" title="Permalink to this headline">¶</a></h3>
+<p>To route CFI checks to the target DSO’s __cfi_check function, a
+mapping from possible virtual / indirect call targets to
+the corresponding __cfi_check functions is maintained. This mapping is
+implemented as a sparse array of 2 bytes for every possible page (4096
+bytes) of memory. The table is kept readonly (FIXME: not yet) most of
+the time.</p>
+<p>There are 3 types of shadow values:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Address in a CFI-instrumented DSO.</li>
+<li>Unchecked address (a “trusted” non-instrumented DSO). Encoded as
+value 0xFFFF.</li>
+<li>Invalid address (everything else). Encoded as value 0.</li>
+</ul>
+</div></blockquote>
+<p>For a CFI-instrumented DSO, a shadow value encodes the address of the
+__cfi_check function for all call targets in the corresponding memory
+page. If Addr is the target address, and V is the shadow value, then
+the address of __cfi_check is calculated as</p>
+<div class="highlight-none"><div class="highlight"><pre>__cfi_check = AlignUpTo(Addr, 4096) - (V + 1) * 4096
+</pre></div>
+</div>
+<p>This works as long as __cfi_check is aligned by 4096 bytes and located
+below any call targets in its DSO, but not more than 256MB apart from
+them.</p>
+</div>
+<div class="section" id="cfi-slowpath">
+<h3>CFI_SlowPath<a class="headerlink" href="#cfi-slowpath" title="Permalink to this headline">¶</a></h3>
+<p>The slow path check is implemented in compiler-rt library as</p>
+<div class="highlight-none"><div class="highlight"><pre>void __cfi_slowpath(uint64 CallSiteTypeId, void *TargetAddr)
+</pre></div>
+</div>
+<p>This functions loads a shadow value for <tt class="docutils literal"><span class="pre">TargetAddr</span></tt>, finds the
+address of __cfi_check as described above and calls that.</p>
+</div>
+<div class="section" id="position-independent-executable-requirement">
+<h3>Position-independent executable requirement<a class="headerlink" href="#position-independent-executable-requirement" title="Permalink to this headline">¶</a></h3>
+<p>Cross-DSO CFI mode requires that the main executable is built as PIE.
+In non-PIE executables the address of an external function (taken from
+the main executable) is the address of that function’s PLT record in
+the main executable. This would break the CFI checks.</p>
+</div>
+</div>
+<div class="section" id="hardware-support">
+<h2>Hardware support<a class="headerlink" href="#hardware-support" title="Permalink to this headline">¶</a></h2>
+<p>We believe that the above design can be efficiently implemented in hardware.
+A single new instruction added to an ISA would allow to perform the CFI check
+with fewer bytes per check (smaller code size overhead) and potentially more
+efficiently. The current software-only instrumentation requires at least
+32-bytes per check (on x86_64).
+A hardware instruction may probably be less than ~ 12 bytes.
+Such instruction would check that the argument pointer is in-bounds,
+and is properly aligned, and if the checks fail it will either trap (in monolithic scheme)
+or call the slow path function (cross-DSO scheme).
+The bit vector lookup is probably too complex for a hardware implementation.</p>
+<div class="highlight-none"><div class="highlight"><pre>//  This instruction checks that 'Ptr'
+//   * is aligned by (1 << kAlignment) and
+//   * is inside [kRangeBeg, kRangeBeg+(kRangeSize<<kAlignment))
+//  and if the check fails it jumps to the given target (slow path).
+//
+// 'Ptr' is a register, pointing to the virtual function table
+//    or to the function which we need to check. We may require an explicit
+//    fixed register to be used.
+// 'kAlignment' is a 4-bit constant.
+// 'kRangeSize' is a ~20-bit constant.
+// 'kRangeBeg' is a PC-relative constant (~28 bits)
+//    pointing to the beginning of the allowed range for 'Ptr'.
+// 'kFailedCheckTarget': is a PC-relative constant (~28 bits)
+//    representing the target to branch to when the check fails.
+//    If kFailedCheckTarget==0, the process will trap
+//    (monolithic binary scheme).
+//    Otherwise it will jump to a handler that implements `CFI_SlowPath`
+//    (cross-DSO scheme).
+CFI_Check(Ptr, kAlignment, kRangeSize, kRangeBeg, kFailedCheckTarget) {
+   if (Ptr < kRangeBeg ||
+       Ptr >= kRangeBeg + (kRangeSize << kAlignment) ||
+       Ptr & ((1 << kAlignment) - 1))
+         Jump(kFailedCheckTarget);
+}
+</pre></div>
+</div>
+<p>An alternative and more compact enconding would not use <cite>kFailedCheckTarget</cite>,
+and will trap on check failure instead.
+This will allow us to fit the instruction into <strong>8-9 bytes</strong>.
+The cross-DSO checks will be performed by a trap handler and
+performance-critical ones will have to be black-listed and checked using the
+software-only scheme.</p>
+<p>Note that such hardware extension would be complementary to checks
+at the callee side, such as e.g. <strong>Intel ENDBRANCH</strong>.
+Moreover, CFI would have two benefits over ENDBRANCH: a) precision and b)
+ability to protect against invalid casts between polymorphic types.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="ControlFlowIntegrity.html">Control Flow Integrity</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LTOVisibility.html">LTO Visibility</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/CrossCompilation.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/CrossCompilation.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/CrossCompilation.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/CrossCompilation.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,259 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Cross-compilation using Clang — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="next" title="Thread Safety Analysis" href="ThreadSafetyAnalysis.html" />
+    <link rel="prev" title="Diagnostic flags in Clang" href="DiagnosticsReference.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>Cross-compilation using Clang</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="DiagnosticsReference.html">Diagnostic flags in Clang</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ThreadSafetyAnalysis.html">Thread Safety Analysis</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="cross-compilation-using-clang">
+<h1>Cross-compilation using Clang<a class="headerlink" href="#cross-compilation-using-clang" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document will guide you in choosing the right Clang options
+for cross-compiling your code to a different architecture. It assumes you
+already know how to compile the code in question for the host architecture,
+and that you know how to choose additional include and library paths.</p>
+<p>However, this document is <em>not</em> a “how to” and won’t help you setting your
+build system or Makefiles, nor choosing the right CMake options, etc.
+Also, it does not cover all the possible options, nor does it contain
+specific examples for specific architectures. For a concrete example, the
+<a class="reference external" href="http://llvm.org/docs/HowToCrossCompileLLVM.html">instructions for cross-compiling LLVM itself</a> may be of interest.</p>
+<p>After reading this document, you should be familiar with the main issues
+related to cross-compilation, and what main compiler options Clang provides
+for performing cross-compilation.</p>
+</div>
+<div class="section" id="cross-compilation-issues">
+<h2>Cross compilation issues<a class="headerlink" href="#cross-compilation-issues" title="Permalink to this headline">¶</a></h2>
+<p>In GCC world, every host/target combination has its own set of binaries,
+headers, libraries, etc. So, it’s usually simple to download a package
+with all files in, unzip to a directory and point the build system to
+that compiler, that will know about its location and find all it needs to
+when compiling your code.</p>
+<p>On the other hand, Clang/LLVM is natively a cross-compiler, meaning that
+one set of programs can compile to all targets by setting the <tt class="docutils literal"><span class="pre">-target</span></tt>
+option. That makes it a lot easier for programmers wishing to compile to
+different platforms and architectures, and for compiler developers that
+only have to maintain one build system, and for OS distributions, that
+need only one set of main packages.</p>
+<p>But, as is true to any cross-compiler, and given the complexity of
+different architectures, OS’s and options, it’s not always easy finding
+the headers, libraries or binutils to generate target specific code.
+So you’ll need special options to help Clang understand what target
+you’re compiling to, where your tools are, etc.</p>
+<p>Another problem is that compilers come with standard libraries only (like
+<tt class="docutils literal"><span class="pre">compiler-rt</span></tt>, <tt class="docutils literal"><span class="pre">libcxx</span></tt>, <tt class="docutils literal"><span class="pre">libgcc</span></tt>, <tt class="docutils literal"><span class="pre">libm</span></tt>, etc), so you’ll have to
+find and make available to the build system, every other library required
+to build your software, that is specific to your target. It’s not enough to
+have your host’s libraries installed.</p>
+<p>Finally, not all toolchains are the same, and consequently, not every Clang
+option will work magically. Some options, like <tt class="docutils literal"><span class="pre">--sysroot</span></tt> (which
+effectively changes the logical root for headers and libraries), assume
+all your binaries and libraries are in the same directory, which may not
+true when your cross-compiler was installed by the distribution’s package
+management. So, for each specific case, you may use more than one
+option, and in most cases, you’ll end up setting include paths (<tt class="docutils literal"><span class="pre">-I</span></tt>) and
+library paths (<tt class="docutils literal"><span class="pre">-L</span></tt>) manually.</p>
+<dl class="docutils">
+<dt>To sum up, different toolchains can:</dt>
+<dd><ul class="first last simple">
+<li>be host/target specific or more flexible</li>
+<li>be in a single directory, or spread out across your system</li>
+<li>have different sets of libraries and headers by default</li>
+<li>need special options, which your build system won’t be able to figure
+out by itself</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="general-cross-compilation-options-in-clang">
+<h2>General Cross-Compilation Options in Clang<a class="headerlink" href="#general-cross-compilation-options-in-clang" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="target-triple">
+<h3>Target Triple<a class="headerlink" href="#target-triple" title="Permalink to this headline">¶</a></h3>
+<p>The basic option is to define the target architecture. For that, use
+<tt class="docutils literal"><span class="pre">-target</span> <span class="pre"><triple></span></tt>. If you don’t specify the target, CPU names won’t
+match (since Clang assumes the host triple), and the compilation will
+go ahead, creating code for the host platform, which will break later
+on when assembling or linking.</p>
+<dl class="docutils">
+<dt>The triple has the general format <tt class="docutils literal"><span class="pre"><arch><sub>-<vendor>-<sys>-<abi></span></tt>, where:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">arch</span></tt> = <tt class="docutils literal"><span class="pre">x86_64</span></tt>, <tt class="docutils literal"><span class="pre">i386</span></tt>, <tt class="docutils literal"><span class="pre">arm</span></tt>, <tt class="docutils literal"><span class="pre">thumb</span></tt>, <tt class="docutils literal"><span class="pre">mips</span></tt>, etc.</li>
+<li><tt class="docutils literal"><span class="pre">sub</span></tt> = for ex. on ARM: <tt class="docutils literal"><span class="pre">v5</span></tt>, <tt class="docutils literal"><span class="pre">v6m</span></tt>, <tt class="docutils literal"><span class="pre">v7a</span></tt>, <tt class="docutils literal"><span class="pre">v7m</span></tt>, etc.</li>
+<li><tt class="docutils literal"><span class="pre">vendor</span></tt> = <tt class="docutils literal"><span class="pre">pc</span></tt>, <tt class="docutils literal"><span class="pre">apple</span></tt>, <tt class="docutils literal"><span class="pre">nvidia</span></tt>, <tt class="docutils literal"><span class="pre">ibm</span></tt>, etc.</li>
+<li><tt class="docutils literal"><span class="pre">sys</span></tt> = <tt class="docutils literal"><span class="pre">none</span></tt>, <tt class="docutils literal"><span class="pre">linux</span></tt>, <tt class="docutils literal"><span class="pre">win32</span></tt>, <tt class="docutils literal"><span class="pre">darwin</span></tt>, <tt class="docutils literal"><span class="pre">cuda</span></tt>, etc.</li>
+<li><tt class="docutils literal"><span class="pre">abi</span></tt> = <tt class="docutils literal"><span class="pre">eabi</span></tt>, <tt class="docutils literal"><span class="pre">gnu</span></tt>, <tt class="docutils literal"><span class="pre">android</span></tt>, <tt class="docutils literal"><span class="pre">macho</span></tt>, <tt class="docutils literal"><span class="pre">elf</span></tt>, etc.</li>
+</ul>
+</dd>
+</dl>
+<p>The sub-architecture options are available for their own architectures,
+of course, so “x86v7a” doesn’t make sense. The vendor needs to be
+specified only if there’s a relevant change, for instance between PC
+and Apple. Most of the time it can be omitted (and Unknown)
+will be assumed, which sets the defaults for the specified architecture.
+The system name is generally the OS (linux, darwin), but could be special
+like the bare-metal “none”.</p>
+<p>When a parameter is not important, it can be omitted, or you can
+choose <tt class="docutils literal"><span class="pre">unknown</span></tt> and the defaults will be used. If you choose a parameter
+that Clang doesn’t know, like <tt class="docutils literal"><span class="pre">blerg</span></tt>, it’ll ignore and assume
+<tt class="docutils literal"><span class="pre">unknown</span></tt>, which is not always desired, so be careful.</p>
+<p>Finally, the ABI option is something that will pick default CPU/FPU,
+define the specific behaviour of your code (PCS, extensions),
+and also choose the correct library calls, etc.</p>
+</div>
+<div class="section" id="cpu-fpu-abi">
+<h3>CPU, FPU, ABI<a class="headerlink" href="#cpu-fpu-abi" title="Permalink to this headline">¶</a></h3>
+<p>Once your target is specified, it’s time to pick the hardware you’ll
+be compiling to. For every architecture, a default set of CPU/FPU/ABI
+will be chosen, so you’ll almost always have to change it via flags.</p>
+<dl class="docutils">
+<dt>Typical flags include:</dt>
+<dd><ul class="first last simple">
+<li><tt class="docutils literal"><span class="pre">-mcpu=<cpu-name></span></tt>, like x86-64, swift, cortex-a15</li>
+<li><tt class="docutils literal"><span class="pre">-mfpu=<fpu-name></span></tt>, like SSE3, NEON, controlling the FP unit available</li>
+<li><tt class="docutils literal"><span class="pre">-mfloat-abi=<fabi></span></tt>, like soft, hard, controlling which registers
+to use for floating-point</li>
+</ul>
+</dd>
+</dl>
+<p>The default is normally the common denominator, so that Clang doesn’t
+generate code that breaks. But that also means you won’t get the best
+code for your specific hardware, which may mean orders of magnitude
+slower than you expect.</p>
+<p>For example, if your target is <tt class="docutils literal"><span class="pre">arm-none-eabi</span></tt>, the default CPU will
+be <tt class="docutils literal"><span class="pre">arm7tdmi</span></tt> using soft float, which is extremely slow on modern cores,
+whereas if your triple is <tt class="docutils literal"><span class="pre">armv7a-none-eabi</span></tt>, it’ll be Cortex-A8 with
+NEON, but still using soft-float, which is much better, but still not
+great.</p>
+</div>
+<div class="section" id="toolchain-options">
+<h3>Toolchain Options<a class="headerlink" href="#toolchain-options" title="Permalink to this headline">¶</a></h3>
+<p>There are three main options to control access to your cross-compiler:
+<tt class="docutils literal"><span class="pre">--sysroot</span></tt>, <tt class="docutils literal"><span class="pre">-I</span></tt>, and <tt class="docutils literal"><span class="pre">-L</span></tt>. The two last ones are well known,
+but they’re particularly important for additional libraries
+and headers that are specific to your target.</p>
+<p>There are two main ways to have a cross-compiler:</p>
+<ol class="arabic">
+<li><p class="first">When you have extracted your cross-compiler from a zip file into
+a directory, you have to use <tt class="docutils literal"><span class="pre">--sysroot=<path></span></tt>. The path is the
+root directory where you have unpacked your file, and Clang will
+look for the directories <tt class="docutils literal"><span class="pre">bin</span></tt>, <tt class="docutils literal"><span class="pre">lib</span></tt>, <tt class="docutils literal"><span class="pre">include</span></tt> in there.</p>
+<p>In this case, your setup should be pretty much done (if no
+additional headers or libraries are needed), as Clang will find
+all binaries it needs (assembler, linker, etc) in there.</p>
+</li>
+<li><p class="first">When you have installed via a package manager (modern Linux
+distributions have cross-compiler packages available), make
+sure the target triple you set is <em>also</em> the prefix of your
+cross-compiler toolchain.</p>
+<p>In this case, Clang will find the other binaries (assembler,
+linker), but not always where the target headers and libraries
+are. People add system-specific clues to Clang often, but as
+things change, it’s more likely that it won’t find than the
+other way around.</p>
+<p>So, here, you’ll be a lot safer if you specify the include/library
+directories manually (via <tt class="docutils literal"><span class="pre">-I</span></tt> and <tt class="docutils literal"><span class="pre">-L</span></tt>).</p>
+</li>
+</ol>
+</div>
+</div>
+<div class="section" id="target-specific-libraries">
+<h2>Target-Specific Libraries<a class="headerlink" href="#target-specific-libraries" title="Permalink to this headline">¶</a></h2>
+<p>All libraries that you compile as part of your build will be
+cross-compiled to your target, and your build system will probably
+find them in the right place. But all dependencies that are
+normally checked against (like <tt class="docutils literal"><span class="pre">libxml</span></tt> or <tt class="docutils literal"><span class="pre">libz</span></tt> etc) will match
+against the host platform, not the target.</p>
+<p>So, if the build system is not aware that you want to cross-compile
+your code, it will get every dependency wrong, and your compilation
+will fail during build time, not configure time.</p>
+<p>Also, finding the libraries for your target are not as easy
+as for your host machine. There aren’t many cross-libraries available
+as packages to most OS’s, so you’ll have to either cross-compile them
+from source, or download the package for your target platform,
+extract the libraries and headers, put them in specific directories
+and add <tt class="docutils literal"><span class="pre">-I</span></tt> and <tt class="docutils literal"><span class="pre">-L</span></tt> pointing to them.</p>
+<p>Also, some libraries have different dependencies on different targets,
+so configuration tools to find dependencies in the host can get the
+list wrong for the target platform. This means that the configuration
+of your build can get things wrong when setting their own library
+paths, and you’ll have to augment it via additional flags (configure,
+Make, CMake, etc).</p>
+<div class="section" id="multilibs">
+<h3>Multilibs<a class="headerlink" href="#multilibs" title="Permalink to this headline">¶</a></h3>
+<p>When you want to cross-compile to more than one configuration, for
+example hard-float-ARM and soft-float-ARM, you’ll have to have multiple
+copies of your libraries and (possibly) headers.</p>
+<p>Some Linux distributions have support for Multilib, which handle that
+for you in an easier way, but if you’re not careful and, for instance,
+forget to specify <tt class="docutils literal"><span class="pre">-ccc-gcc-name</span> <span class="pre">armv7l-linux-gnueabihf-gcc</span></tt> (which
+uses hard-float), Clang will pick the <tt class="docutils literal"><span class="pre">armv7l-linux-gnueabi-ld</span></tt>
+(which uses soft-float) and linker errors will happen.</p>
+<p>The same is true if you’re compiling for different ABIs, like <tt class="docutils literal"><span class="pre">gnueabi</span></tt>
+and <tt class="docutils literal"><span class="pre">androideabi</span></tt>, and might even link and run, but produce run-time
+errors, which are much harder to track down and fix.</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="DiagnosticsReference.html">Diagnostic flags in Clang</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ThreadSafetyAnalysis.html">Thread Safety Analysis</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/DataFlowSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/DataFlowSanitizer.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/DataFlowSanitizer.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/DataFlowSanitizer.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,221 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>DataFlowSanitizer — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="next" title="DataFlowSanitizer Design Document" href="DataFlowSanitizerDesign.html" />
+    <link rel="prev" title="UndefinedBehaviorSanitizer" href="UndefinedBehaviorSanitizer.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>DataFlowSanitizer</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="UndefinedBehaviorSanitizer.html">UndefinedBehaviorSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DataFlowSanitizerDesign.html">DataFlowSanitizer Design Document</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="dataflowsanitizer">
+<h1>DataFlowSanitizer<a class="headerlink" href="#dataflowsanitizer" title="Permalink to this headline">¶</a></h1>
+<div class="toctree-wrapper compound">
+</div>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#usage" id="id2">Usage</a><ul>
+<li><a class="reference internal" href="#abi-list" id="id3">ABI List</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#example" id="id4">Example</a></li>
+<li><a class="reference internal" href="#current-status" id="id5">Current status</a></li>
+<li><a class="reference internal" href="#design" id="id6">Design</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>DataFlowSanitizer is a generalised dynamic data flow analysis.</p>
+<p>Unlike other Sanitizer tools, this tool is not designed to detect a
+specific class of bugs on its own.  Instead, it provides a generic
+dynamic data flow analysis framework to be used by clients to help
+detect application-specific issues within their own code.</p>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id2">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>With no program changes, applying DataFlowSanitizer to a program
+will not alter its behavior.  To use DataFlowSanitizer, the program
+uses API functions to apply tags to data to cause it to be tracked, and to
+check the tag of a specific data item.  DataFlowSanitizer manages
+the propagation of tags through the program according to its data flow.</p>
+<p>The APIs are defined in the header file <tt class="docutils literal"><span class="pre">sanitizer/dfsan_interface.h</span></tt>.
+For further information about each function, please refer to the header
+file.</p>
+<div class="section" id="abi-list">
+<h3><a class="toc-backref" href="#id3">ABI List</a><a class="headerlink" href="#abi-list" title="Permalink to this headline">¶</a></h3>
+<p>DataFlowSanitizer uses a list of functions known as an ABI list to decide
+whether a call to a specific function should use the operating system’s native
+ABI or whether it should use a variant of this ABI that also propagates labels
+through function parameters and return values.  The ABI list file also controls
+how labels are propagated in the former case.  DataFlowSanitizer comes with a
+default ABI list which is intended to eventually cover the glibc library on
+Linux but it may become necessary for users to extend the ABI list in cases
+where a particular library or function cannot be instrumented (e.g. because
+it is implemented in assembly or another language which DataFlowSanitizer does
+not support) or a function is called from a library or function which cannot
+be instrumented.</p>
+<p>DataFlowSanitizer’s ABI list file is a <a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>.
+The pass treats every function in the <tt class="docutils literal"><span class="pre">uninstrumented</span></tt> category in the
+ABI list file as conforming to the native ABI.  Unless the ABI list contains
+additional categories for those functions, a call to one of those functions
+will produce a warning message, as the labelling behavior of the function
+is unknown.  The other supported categories are <tt class="docutils literal"><span class="pre">discard</span></tt>, <tt class="docutils literal"><span class="pre">functional</span></tt>
+and <tt class="docutils literal"><span class="pre">custom</span></tt>.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">discard</span></tt> – To the extent that this function writes to (user-accessible)
+memory, it also updates labels in shadow memory (this condition is trivially
+satisfied for functions which do not write to user-accessible memory).  Its
+return value is unlabelled.</li>
+<li><tt class="docutils literal"><span class="pre">functional</span></tt> – Like <tt class="docutils literal"><span class="pre">discard</span></tt>, except that the label of its return value
+is the union of the label of its arguments.</li>
+<li><tt class="docutils literal"><span class="pre">custom</span></tt> – Instead of calling the function, a custom wrapper <tt class="docutils literal"><span class="pre">__dfsw_F</span></tt>
+is called, where <tt class="docutils literal"><span class="pre">F</span></tt> is the name of the function.  This function may wrap
+the original function or provide its own implementation.  This category is
+generally used for uninstrumentable functions which write to user-accessible
+memory or which have more complex label propagation behavior.  The signature
+of <tt class="docutils literal"><span class="pre">__dfsw_F</span></tt> is based on that of <tt class="docutils literal"><span class="pre">F</span></tt> with each argument having a
+label of type <tt class="docutils literal"><span class="pre">dfsan_label</span></tt> appended to the argument list.  If <tt class="docutils literal"><span class="pre">F</span></tt>
+is of non-void return type a final argument of type <tt class="docutils literal"><span class="pre">dfsan_label</span> <span class="pre">*</span></tt>
+is appended to which the custom function can store the label for the
+return value.  For example:</li>
+</ul>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">);</span>
+<span class="kt">void</span> <span class="nf">__dfsw_f</span><span class="p">(</span><span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="n">dfsan_label</span> <span class="n">x_label</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="o">*</span><span class="nf">memcpy</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">n</span><span class="p">);</span>
+<span class="kt">void</span> <span class="o">*</span><span class="nf">__dfsw_memcpy</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="n">dest</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">src</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">n</span><span class="p">,</span>
+                    <span class="n">dfsan_label</span> <span class="n">dest_label</span><span class="p">,</span> <span class="n">dfsan_label</span> <span class="n">src_label</span><span class="p">,</span>
+                    <span class="n">dfsan_label</span> <span class="n">n_label</span><span class="p">,</span> <span class="n">dfsan_label</span> <span class="o">*</span><span class="n">ret_label</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>If a function defined in the translation unit being compiled belongs to the
+<tt class="docutils literal"><span class="pre">uninstrumented</span></tt> category, it will be compiled so as to conform to the
+native ABI.  Its arguments will be assumed to be unlabelled, but it will
+propagate labels in shadow memory.</p>
+<p>For example:</p>
+<div class="highlight-none"><div class="highlight"><pre># main is called by the C runtime using the native ABI.
+fun:main=uninstrumented
+fun:main=discard
+
+# malloc only writes to its internal data structures, not user-accessible memory.
+fun:malloc=uninstrumented
+fun:malloc=discard
+
+# tolower is a pure function.
+fun:tolower=uninstrumented
+fun:tolower=functional
+
+# memcpy needs to copy the shadow from the source to the destination region.
+# This is done in a custom function.
+fun:memcpy=uninstrumented
+fun:memcpy=custom
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="example">
+<h2><a class="toc-backref" href="#id4">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
+<p>The following program demonstrates label propagation by checking that
+the correct labels are propagated.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <sanitizer/dfsan_interface.h></span>
+<span class="cp">#include <assert.h></span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+  <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+  <span class="n">dfsan_label</span> <span class="n">i_label</span> <span class="o">=</span> <span class="n">dfsan_create_label</span><span class="p">(</span><span class="s">"i"</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+  <span class="n">dfsan_set_label</span><span class="p">(</span><span class="n">i_label</span><span class="p">,</span> <span class="o">&</span><span class="n">i</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">i</span><span class="p">));</span>
+
+  <span class="kt">int</span> <span class="n">j</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span>
+  <span class="n">dfsan_label</span> <span class="n">j_label</span> <span class="o">=</span> <span class="n">dfsan_create_label</span><span class="p">(</span><span class="s">"j"</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+  <span class="n">dfsan_set_label</span><span class="p">(</span><span class="n">j_label</span><span class="p">,</span> <span class="o">&</span><span class="n">j</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">j</span><span class="p">));</span>
+
+  <span class="kt">int</span> <span class="n">k</span> <span class="o">=</span> <span class="mi">3</span><span class="p">;</span>
+  <span class="n">dfsan_label</span> <span class="n">k_label</span> <span class="o">=</span> <span class="n">dfsan_create_label</span><span class="p">(</span><span class="s">"k"</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+  <span class="n">dfsan_set_label</span><span class="p">(</span><span class="n">k_label</span><span class="p">,</span> <span class="o">&</span><span class="n">k</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="n">k</span><span class="p">));</span>
+
+  <span class="n">dfsan_label</span> <span class="n">ij_label</span> <span class="o">=</span> <span class="n">dfsan_get_label</span><span class="p">(</span><span class="n">i</span> <span class="o">+</span> <span class="n">j</span><span class="p">);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ij_label</span><span class="p">,</span> <span class="n">i_label</span><span class="p">));</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ij_label</span><span class="p">,</span> <span class="n">j_label</span><span class="p">));</span>
+  <span class="n">assert</span><span class="p">(</span><span class="o">!</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ij_label</span><span class="p">,</span> <span class="n">k_label</span><span class="p">));</span>
+
+  <span class="n">dfsan_label</span> <span class="n">ijk_label</span> <span class="o">=</span> <span class="n">dfsan_get_label</span><span class="p">(</span><span class="n">i</span> <span class="o">+</span> <span class="n">j</span> <span class="o">+</span> <span class="n">k</span><span class="p">);</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ijk_label</span><span class="p">,</span> <span class="n">i_label</span><span class="p">));</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ijk_label</span><span class="p">,</span> <span class="n">j_label</span><span class="p">));</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">dfsan_has_label</span><span class="p">(</span><span class="n">ijk_label</span><span class="p">,</span> <span class="n">k_label</span><span class="p">));</span>
+
+  <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id5">Current status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<p>DataFlowSanitizer is a work in progress, currently under development for
+x86_64 Linux.</p>
+</div>
+<div class="section" id="design">
+<h2><a class="toc-backref" href="#id6">Design</a><a class="headerlink" href="#design" title="Permalink to this headline">¶</a></h2>
+<p>Please refer to the <a class="reference internal" href="DataFlowSanitizerDesign.html"><em>design document</em></a>.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="UndefinedBehaviorSanitizer.html">UndefinedBehaviorSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="DataFlowSanitizerDesign.html">DataFlowSanitizer Design Document</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/4.0.0/tools/clang/docs/DataFlowSanitizerDesign.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/4.0.0/tools/clang/docs/DataFlowSanitizerDesign.html?rev=297634&view=auto
==============================================================================
--- www-releases/trunk/4.0.0/tools/clang/docs/DataFlowSanitizerDesign.html (added)
+++ www-releases/trunk/4.0.0/tools/clang/docs/DataFlowSanitizerDesign.html Mon Mar 13 11:30:12 2017
@@ -0,0 +1,291 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>DataFlowSanitizer Design Document — Clang 4 documentation</title>
+    
+    <link rel="stylesheet" href="_static/haiku.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '4',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 4 documentation" href="index.html" />
+    <link rel="up" title="DataFlowSanitizer" href="DataFlowSanitizer.html" />
+    <link rel="next" title="LeakSanitizer" href="LeakSanitizer.html" />
+    <link rel="prev" title="DataFlowSanitizer" href="DataFlowSanitizer.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 4 documentation</span></a></h1>
+        <h2 class="heading"><span>DataFlowSanitizer Design Document</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="DataFlowSanitizer.html">DataFlowSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LeakSanitizer.html">LeakSanitizer</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="dataflowsanitizer-design-document">
+<h1>DataFlowSanitizer Design Document<a class="headerlink" href="#dataflowsanitizer-design-document" title="Permalink to this headline">¶</a></h1>
+<p>This document sets out the design for DataFlowSanitizer, a general
+dynamic data flow analysis.  Unlike other Sanitizer tools, this tool is
+not designed to detect a specific class of bugs on its own. Instead,
+it provides a generic dynamic data flow analysis framework to be used
+by clients to help detect application-specific issues within their
+own code.</p>
+<p>DataFlowSanitizer is a program instrumentation which can associate
+a number of taint labels with any data stored in any memory region
+accessible by the program. The analysis is dynamic, which means that
+it operates on a running program, and tracks how the labels propagate
+through that program. The tool shall support a large (>100) number
+of labels, such that programs which operate on large numbers of data
+items may be analysed with each data item being tracked separately.</p>
+<div class="section" id="use-cases">
+<h2>Use Cases<a class="headerlink" href="#use-cases" title="Permalink to this headline">¶</a></h2>
+<p>This instrumentation can be used as a tool to help monitor how data
+flows from a program’s inputs (sources) to its outputs (sinks).
+This has applications from a privacy/security perspective in that
+one can audit how a sensitive data item is used within a program and
+ensure it isn’t exiting the program anywhere it shouldn’t be.</p>
+</div>
+<div class="section" id="interface">
+<h2>Interface<a class="headerlink" href="#interface" title="Permalink to this headline">¶</a></h2>
+<p>A number of functions are provided which will create taint labels,
+attach labels to memory regions and extract the set of labels
+associated with a specific memory region. These functions are declared
+in the header file <tt class="docutils literal"><span class="pre">sanitizer/dfsan_interface.h</span></tt>.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="c1">/// Creates and returns a base label with the given description and user data.</span>
+<span class="n">dfsan_label</span> <span class="nf">dfsan_create_label</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">desc</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">userdata</span><span class="p">);</span>
+
+<span class="c1">/// Sets the label for each address in [addr,addr+size) to \c label.</span>
+<span class="kt">void</span> <span class="nf">dfsan_set_label</span><span class="p">(</span><span class="n">dfsan_label</span> <span class="n">label</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">addr</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span>
+
+<span class="c1">/// Sets the label for each address in [addr,addr+size) to the union of the</span>
+<span class="c1">/// current label for that address and \c label.</span>
+<span class="kt">void</span> <span class="nf">dfsan_add_label</span><span class="p">(</span><span class="n">dfsan_label</span> <span class="n">label</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">addr</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span>
+
+<span class="c1">/// Retrieves the label associated with the given data.</span>
+<span class="c1">///</span>
+<span class="c1">/// The type of 'data' is arbitrary.  The function accepts a value of any type,</span>
+<span class="c1">/// which can be truncated or extended (implicitly or explicitly) as necessary.</span>
+<span class="c1">/// The truncation/extension operations will preserve the label of the original</span>
+<span class="c1">/// value.</span>
+<span class="n">dfsan_label</span> <span class="nf">dfsan_get_label</span><span class="p">(</span><span class="kt">long</span> <span class="n">data</span><span class="p">);</span>
+
+<span class="c1">/// Retrieves a pointer to the dfsan_label_info struct for the given label.</span>
+<span class="k">const</span> <span class="k">struct</span> <span class="n">dfsan_label_info</span> <span class="o">*</span><span class="nf">dfsan_get_label_info</span><span class="p">(</span><span class="n">dfsan_label</span> <span class="n">label</span><span class="p">);</span>
+
+<span class="c1">/// Returns whether the given label label contains the label elem.</span>
+<span class="kt">int</span> <span class="nf">dfsan_has_label</span><span class="p">(</span><span class="n">dfsan_label</span> <span class="n">label</span><span class="p">,</span> <span class="n">dfsan_label</span> <span class="n">elem</span><span class="p">);</span>
+
+<span class="c1">/// If the given label label contains a label with the description desc, returns</span>
+<span class="c1">/// that label, else returns 0.</span>
+<span class="n">dfsan_label</span> <span class="nf">dfsan_has_label_with_desc</span><span class="p">(</span><span class="n">dfsan_label</span> <span class="n">label</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">desc</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="taint-label-representation">
+<h2>Taint label representation<a class="headerlink" href="#taint-label-representation" title="Permalink to this headline">¶</a></h2>
+<p>As stated above, the tool must track a large number of taint
+labels. This poses an implementation challenge, as most multiple-label
+tainting systems assign one label per bit to shadow storage, and
+union taint labels using a bitwise or operation. This will not scale
+to clients which use hundreds or thousands of taint labels, as the
+label union operation becomes O(n) in the number of supported labels,
+and data associated with it will quickly dominate the live variable
+set, causing register spills and hampering performance.</p>
+<p>Instead, a low overhead approach is proposed which is best-case O(log<sub>2</sub> n) during execution. The underlying assumption is that
+the required space of label unions is sparse, which is a reasonable
+assumption to make given that we are optimizing for the case where
+applications mostly copy data from one place to another, without often
+invoking the need for an actual union operation. The representation
+of a taint label is a 16-bit integer, and new labels are allocated
+sequentially from a pool. The label identifier 0 is special, and means
+that the data item is unlabelled.</p>
+<p>When a label union operation is requested at a join point (any
+arithmetic or logical operation with two or more operands, such as
+addition), the code checks whether a union is required, whether the
+same union has been requested before, and whether one union label
+subsumes the other. If so, it returns the previously allocated union
+label. If not, it allocates a new union label from the same pool used
+for new labels.</p>
+<p>Specifically, the instrumentation pass will insert code like this
+to decide the union label <tt class="docutils literal"><span class="pre">lu</span></tt> for a pair of labels <tt class="docutils literal"><span class="pre">l1</span></tt>
+and <tt class="docutils literal"><span class="pre">l2</span></tt>:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">l1</span> <span class="o">==</span> <span class="n">l2</span><span class="p">)</span>
+  <span class="n">lu</span> <span class="o">=</span> <span class="n">l1</span><span class="p">;</span>
+<span class="k">else</span>
+  <span class="n">lu</span> <span class="o">=</span> <span class="n">__dfsan_union</span><span class="p">(</span><span class="n">l1</span><span class="p">,</span> <span class="n">l2</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The equality comparison is outlined, to provide an early exit in
+the common cases where the program is processing unlabelled data, or
+where the two data items have the same label.  <tt class="docutils literal"><span class="pre">__dfsan_union</span></tt> is
+a runtime library function which performs all other union computation.</p>
+<p>Further optimizations are possible, for example if <tt class="docutils literal"><span class="pre">l1</span></tt> is known
+at compile time to be zero (e.g. it is derived from a constant),
+<tt class="docutils literal"><span class="pre">l2</span></tt> can be used for <tt class="docutils literal"><span class="pre">lu</span></tt>, and vice versa.</p>
+</div>
+<div class="section" id="memory-layout-and-label-management">
+<h2>Memory layout and label management<a class="headerlink" href="#memory-layout-and-label-management" title="Permalink to this headline">¶</a></h2>
+<p>The following is the current memory layout for Linux/x86_64:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="30%" />
+<col width="30%" />
+<col width="40%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Start</th>
+<th class="head">End</th>
+<th class="head">Use</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>0x700000008000</td>
+<td>0x800000000000</td>
+<td>application memory</td>
+</tr>
+<tr class="row-odd"><td>0x200200000000</td>
+<td>0x700000008000</td>
+<td>unused</td>
+</tr>
+<tr class="row-even"><td>0x200000000000</td>
+<td>0x200200000000</td>
+<td>union table</td>
+</tr>
+<tr class="row-odd"><td>0x000000010000</td>
+<td>0x200000000000</td>
+<td>shadow memory</td>
+</tr>
+<tr class="row-even"><td>0x000000000000</td>
+<td>0x000000010000</td>
+<td>reserved by kernel</td>
+</tr>
+</tbody>
+</table>
+<p>Each byte of application memory corresponds to two bytes of shadow
+memory, which are used to store its taint label. As for LLVM SSA
+registers, we have not found it necessary to associate a label with
+each byte or bit of data, as some other tools do. Instead, labels are
+associated directly with registers.  Loads will result in a union of
+all shadow labels corresponding to bytes loaded (which most of the
+time will be short circuited by the initial comparison) and stores will
+result in a copy of the label to the shadow of all bytes stored to.</p>
+</div>
+<div class="section" id="propagating-labels-through-arguments">
+<h2>Propagating labels through arguments<a class="headerlink" href="#propagating-labels-through-arguments" title="Permalink to this headline">¶</a></h2>
+<p>In order to propagate labels through function arguments and return values,
+DataFlowSanitizer changes the ABI of each function in the translation unit.
+There are currently two supported ABIs:</p>
+<ul class="simple">
+<li>Args – Argument and return value labels are passed through additional
+arguments and by modifying the return type.</li>
+<li>TLS – Argument and return value labels are passed through TLS variables
+<tt class="docutils literal"><span class="pre">__dfsan_arg_tls</span></tt> and <tt class="docutils literal"><span class="pre">__dfsan_retval_tls</span></tt>.</li>
+</ul>
+<p>The main advantage of the TLS ABI is that it is more tolerant of ABI mismatches
+(TLS storage is not shared with any other form of storage, whereas extra
+arguments may be stored in registers which under the native ABI are not used
+for parameter passing and thus could contain arbitrary values).  On the other
+hand the args ABI is more efficient and allows ABI mismatches to be more easily
+identified by checking for nonzero labels in nominally unlabelled programs.</p>
+</div>
+<div class="section" id="implementing-the-abi-list">
+<h2>Implementing the ABI list<a class="headerlink" href="#implementing-the-abi-list" title="Permalink to this headline">¶</a></h2>
+<p>The <a class="reference external" href="DataFlowSanitizer.html#abi-list">ABI list</a> provides a list of functions
+which conform to the native ABI, each of which is callable from an instrumented
+program.  This is implemented by replacing each reference to a native ABI
+function with a reference to a function which uses the instrumented ABI.
+Such functions are automatically-generated wrappers for the native functions.
+For example, given the ABI list example provided in the user manual, the
+following wrappers will be generated under the args ABI:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">linkonce_odr</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="vg">@"dfsw$malloc"</span><span class="p">(</span><span class="k">i64</span> <span class="nv-Anonymous">%0</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%1</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv-Anonymous">%2</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@malloc</span><span class="p">(</span><span class="k">i64</span> <span class="nv-Anonymous">%0</span><span class="p">)</span>
+  <span class="nv-Anonymous">%3</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="k">undef</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%2</span><span class="p">,</span> <span class="m">0</span>
+  <span class="nv-Anonymous">%4</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%3</span><span class="p">,</span> <span class="k">i16</span> <span class="m">0</span><span class="p">,</span> <span class="m">1</span>
+  <span class="k">ret</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%4</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="k">linkonce_odr</span> <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i16</span> <span class="p">}</span> <span class="vg">@"dfsw$tolower"</span><span class="p">(</span><span class="k">i32</span> <span class="nv-Anonymous">%0</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%1</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv-Anonymous">%2</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@tolower</span><span class="p">(</span><span class="k">i32</span> <span class="nv-Anonymous">%0</span><span class="p">)</span>
+  <span class="nv-Anonymous">%3</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i16</span> <span class="p">}</span> <span class="k">undef</span><span class="p">,</span> <span class="k">i32</span> <span class="nv-Anonymous">%2</span><span class="p">,</span> <span class="m">0</span>
+  <span class="nv-Anonymous">%4</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%3</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%1</span><span class="p">,</span> <span class="m">1</span>
+  <span class="k">ret</span> <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%4</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="k">linkonce_odr</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="vg">@"dfsw$memcpy"</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%1</span><span class="p">,</span> <span class="k">i64</span> <span class="nv-Anonymous">%2</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%3</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%4</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%5</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv">%labelreturn</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i16</span>
+  <span class="nv-Anonymous">%6</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@__dfsw_memcpy</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%1</span><span class="p">,</span> <span class="k">i64</span> <span class="nv-Anonymous">%2</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%3</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%4</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%5</span><span class="p">,</span> <span class="k">i16</span><span class="p">*</span> <span class="nv">%labelreturn</span><span class="p">)</span>
+  <span class="nv-Anonymous">%7</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i16</span><span class="p">*</span> <span class="nv">%labelreturn</span>
+  <span class="nv-Anonymous">%8</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="k">undef</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%6</span><span class="p">,</span> <span class="m">0</span>
+  <span class="nv-Anonymous">%9</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%8</span><span class="p">,</span> <span class="k">i16</span> <span class="nv-Anonymous">%7</span><span class="p">,</span> <span class="m">1</span>
+  <span class="k">ret</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i16</span> <span class="p">}</span> <span class="nv-Anonymous">%9</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>As an optimization, direct calls to native ABI functions will call the
+native ABI function directly and the pass will compute the appropriate label
+internally.  This has the advantage of reducing the number of union operations
+required when the return value label is known to be zero (i.e. <tt class="docutils literal"><span class="pre">discard</span></tt>
+functions, or <tt class="docutils literal"><span class="pre">functional</span></tt> functions with known unlabelled arguments).</p>
+</div>
+<div class="section" id="checking-abi-consistency">
+<h2>Checking ABI Consistency<a class="headerlink" href="#checking-abi-consistency" title="Permalink to this headline">¶</a></h2>
+<p>DFSan changes the ABI of each function in the module.  This makes it possible
+for a function with the native ABI to be called with the instrumented ABI,
+or vice versa, thus possibly invoking undefined behavior.  A simple way
+of statically detecting instances of this problem is to prepend the prefix
+“dfs$” to the name of each instrumented-ABI function.</p>
+<p>This will not catch every such problem; in particular function pointers passed
+across the instrumented-native barrier cannot be used on the other side.
+These problems could potentially be caught dynamically.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="DataFlowSanitizer.html">DataFlowSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LeakSanitizer.html">LeakSanitizer</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2017, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file




More information about the llvm-commits mailing list