[www-releases] r372328 - Check in 9.0.0 source and docs
Hans Wennborg via llvm-commits
llvm-commits at lists.llvm.org
Thu Sep 19 07:32:55 PDT 2019
Added: www-releases/trunk/9.0.0/tools/clang/docs/ThreadSafetyAnalysis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/ThreadSafetyAnalysis.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/ThreadSafetyAnalysis.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/ThreadSafetyAnalysis.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,897 @@
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Thread Safety Analysis — Clang 9 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="AddressSanitizer" href="AddressSanitizer.html" />
+ <link rel="prev" title="3.5. Region Store" href="analyzer/developer-docs/RegionStore.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>Thread Safety Analysis</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="analyzer/developer-docs/RegionStore.html">3.5. Region Store</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="AddressSanitizer.html">AddressSanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="thread-safety-analysis">
+<h1>Thread Safety Analysis<a class="headerlink" href="#thread-safety-analysis" 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>Clang Thread Safety Analysis is a C++ language extension which warns about
+potential race conditions in code. The analysis is completely static (i.e.
+compile-time); there is no run-time overhead. The analysis is still
+under active development, but it is mature enough to be deployed in an
+industrial setting. It is being developed by Google, in collaboration with
+CERT/SEI, and is used extensively in Googleâs internal code base.</p>
+<p>Thread safety analysis works very much like a type system for multi-threaded
+programs. In addition to declaring the <em>type</em> of data (e.g. <code class="docutils literal notranslate"><span class="pre">int</span></code>, <code class="docutils literal notranslate"><span class="pre">float</span></code>,
+etc.), the programmer can (optionally) declare how access to that data is
+controlled in a multi-threaded environment. For example, if <code class="docutils literal notranslate"><span class="pre">foo</span></code> is
+<em>guarded by</em> the mutex <code class="docutils literal notranslate"><span class="pre">mu</span></code>, then the analysis will issue a warning whenever
+a piece of code reads or writes to <code class="docutils literal notranslate"><span class="pre">foo</span></code> without first locking <code class="docutils literal notranslate"><span class="pre">mu</span></code>.
+Similarly, if there are particular routines that should only be called by
+the GUI thread, then the analysis will warn if other threads call those
+routines.</p>
+<div class="section" id="getting-started">
+<h3>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"mutex.h"</span><span class="cp"></span>
+
+<span class="k">class</span> <span class="nc">BankAccount</span> <span class="p">{</span>
+<span class="k">private</span><span class="o">:</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">balance</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="nf">depositImpl</span><span class="p">(</span><span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">balance</span> <span class="o">+=</span> <span class="n">amount</span><span class="p">;</span> <span class="c1">// WARNING! Cannot write balance without locking mu.</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">withdrawImpl</span><span class="p">(</span><span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">balance</span> <span class="o">-=</span> <span class="n">amount</span><span class="p">;</span> <span class="c1">// OK. Caller must have locked mu.</span>
+ <span class="p">}</span>
+
+<span class="k">public</span><span class="o">:</span>
+ <span class="kt">void</span> <span class="n">withdraw</span><span class="p">(</span><span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">withdrawImpl</span><span class="p">(</span><span class="n">amount</span><span class="p">);</span> <span class="c1">// OK. We've locked mu.</span>
+ <span class="p">}</span> <span class="c1">// WARNING! Failed to unlock mu.</span>
+
+ <span class="kt">void</span> <span class="n">transferFrom</span><span class="p">(</span><span class="n">BankAccount</span><span class="o">&</span> <span class="n">b</span><span class="p">,</span> <span class="kt">int</span> <span class="n">amount</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">b</span><span class="p">.</span><span class="n">withdrawImpl</span><span class="p">(</span><span class="n">amount</span><span class="p">);</span> <span class="c1">// WARNING! Calling withdrawImpl() requires locking b.mu.</span>
+ <span class="n">depositImpl</span><span class="p">(</span><span class="n">amount</span><span class="p">);</span> <span class="c1">// OK. depositImpl() has no requirements.</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>This example demonstrates the basic concepts behind the analysis. The
+<code class="docutils literal notranslate"><span class="pre">GUARDED_BY</span></code> attribute declares that a thread must lock <code class="docutils literal notranslate"><span class="pre">mu</span></code> before it can
+read or write to <code class="docutils literal notranslate"><span class="pre">balance</span></code>, thus ensuring that the increment and decrement
+operations are atomic. Similarly, <code class="docutils literal notranslate"><span class="pre">REQUIRES</span></code> declares that
+the calling thread must lock <code class="docutils literal notranslate"><span class="pre">mu</span></code> before calling <code class="docutils literal notranslate"><span class="pre">withdrawImpl</span></code>.
+Because the caller is assumed to have locked <code class="docutils literal notranslate"><span class="pre">mu</span></code>, it is safe to modify
+<code class="docutils literal notranslate"><span class="pre">balance</span></code> within the body of the method.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">depositImpl()</span></code> method does not have <code class="docutils literal notranslate"><span class="pre">REQUIRES</span></code>, so the
+analysis issues a warning. Thread safety analysis is not inter-procedural, so
+caller requirements must be explicitly declared.
+There is also a warning in <code class="docutils literal notranslate"><span class="pre">transferFrom()</span></code>, because although the method
+locks <code class="docutils literal notranslate"><span class="pre">this->mu</span></code>, it does not lock <code class="docutils literal notranslate"><span class="pre">b.mu</span></code>. The analysis understands
+that these are two separate mutexes, in two different objects.</p>
+<p>Finally, there is a warning in the <code class="docutils literal notranslate"><span class="pre">withdraw()</span></code> method, because it fails to
+unlock <code class="docutils literal notranslate"><span class="pre">mu</span></code>. Every lock must have a corresponding unlock, and the analysis
+will detect both double locks, and double unlocks. A function is allowed to
+acquire a lock without releasing it, (or vice versa), but it must be annotated
+as such (using <code class="docutils literal notranslate"><span class="pre">ACQUIRE</span></code>/<code class="docutils literal notranslate"><span class="pre">RELEASE</span></code>).</p>
+</div>
+<div class="section" id="running-the-analysis">
+<h3>Running The Analysis<a class="headerlink" href="#running-the-analysis" title="Permalink to this headline">¶</a></h3>
+<p>To run the analysis, simply compile with the <code class="docutils literal notranslate"><span class="pre">-Wthread-safety</span></code> flag, e.g.</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>clang -c -Wthread-safety example.cpp
+</pre></div>
+</div>
+<p>Note that this example assumes the presence of a suitably annotated
+<a class="reference internal" href="#mutexheader"><span class="std std-ref">mutex.h</span></a> that declares which methods perform locking,
+unlocking, and so on.</p>
+</div>
+</div>
+<div class="section" id="basic-concepts-capabilities">
+<h2>Basic Concepts: Capabilities<a class="headerlink" href="#basic-concepts-capabilities" title="Permalink to this headline">¶</a></h2>
+<p>Thread safety analysis provides a way of protecting <em>resources</em> with
+<em>capabilities</em>. A resource is either a data member, or a function/method
+that provides access to some underlying resource. The analysis ensures that
+the calling thread cannot access the <em>resource</em> (i.e. call the function, or
+read/write the data) unless it has the <em>capability</em> to do so.</p>
+<p>Capabilities are associated with named C++ objects which declare specific
+methods to acquire and release the capability. The name of the object serves
+to identify the capability. The most common example is a mutex. For example,
+if <code class="docutils literal notranslate"><span class="pre">mu</span></code> is a mutex, then calling <code class="docutils literal notranslate"><span class="pre">mu.Lock()</span></code> causes the calling thread
+to acquire the capability to access data that is protected by <code class="docutils literal notranslate"><span class="pre">mu</span></code>. Similarly,
+calling <code class="docutils literal notranslate"><span class="pre">mu.Unlock()</span></code> releases that capability.</p>
+<p>A thread may hold a capability either <em>exclusively</em> or <em>shared</em>. An exclusive
+capability can be held by only one thread at a time, while a shared capability
+can be held by many threads at the same time. This mechanism enforces a
+multiple-reader, single-writer pattern. Write operations to protected data
+require exclusive access, while read operations require only shared access.</p>
+<p>At any given moment during program execution, a thread holds a specific set of
+capabilities (e.g. the set of mutexes that it has locked.) These act like keys
+or tokens that allow the thread to access a given resource. Just like physical
+security keys, a thread cannot make copy of a capability, nor can it destroy
+one. A thread can only release a capability to another thread, or acquire one
+from another thread. The annotations are deliberately agnostic about the
+exact mechanism used to acquire and release capabilities; it assumes that the
+underlying implementation (e.g. the Mutex implementation) does the handoff in
+an appropriate manner.</p>
+<p>The set of capabilities that are actually held by a given thread at a given
+point in program execution is a run-time concept. The static analysis works
+by calculating an approximation of that set, called the <em>capability
+environment</em>. The capability environment is calculated for every program point,
+and describes the set of capabilities that are statically known to be held, or
+not held, at that particular point. This environment is a conservative
+approximation of the full set of capabilities that will actually held by a
+thread at run-time.</p>
+</div>
+<div class="section" id="reference-guide">
+<h2>Reference Guide<a class="headerlink" href="#reference-guide" title="Permalink to this headline">¶</a></h2>
+<p>The thread safety analysis uses attributes to declare threading constraints.
+Attributes must be attached to named declarations, such as classes, methods,
+and data members. Users are <em>strongly advised</em> to define macros for the various
+attributes; example definitions can be found in <a class="reference internal" href="#mutexheader"><span class="std std-ref">mutex.h</span></a>, below.
+The following documentation assumes the use of macros.</p>
+<p>For historical reasons, prior versions of thread safety used macro names that
+were very lock-centric. These macros have since been renamed to fit a more
+general capability model. The prior names are still in use, and will be
+mentioned under the tag <em>previously</em> where appropriate.</p>
+<div class="section" id="guarded-by-c-and-pt-guarded-by-c">
+<h3>GUARDED_BY(c) and PT_GUARDED_BY(c)<a class="headerlink" href="#guarded-by-c-and-pt-guarded-by-c" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">GUARDED_BY</span></code> is an attribute on data members, which declares that the data
+member is protected by the given capability. Read operations on the data
+require shared access, while write operations require exclusive access.</p>
+<p><code class="docutils literal notranslate"><span class="pre">PT_GUARDED_BY</span></code> is similar, but is intended for use on pointers and smart
+pointers. There is no constraint on the data member itself, but the <em>data that
+it points to</em> is protected by the given capability.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="kt">int</span> <span class="o">*</span><span class="n">p1</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="kt">int</span> <span class="o">*</span><span class="n">p2</span> <span class="nf">PT_GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="n">unique_ptr</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">p3</span> <span class="n">PT_GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">p1</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="c1">// Warning!</span>
+
+ <span class="o">*</span><span class="n">p2</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span> <span class="c1">// Warning!</span>
+ <span class="n">p2</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">int</span><span class="p">;</span> <span class="c1">// OK.</span>
+
+ <span class="o">*</span><span class="n">p3</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span> <span class="c1">// Warning!</span>
+ <span class="n">p3</span><span class="p">.</span><span class="n">reset</span><span class="p">(</span><span class="k">new</span> <span class="kt">int</span><span class="p">);</span> <span class="c1">// OK.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="requires-requires-shared">
+<h3>REQUIRES(â¦), REQUIRES_SHARED(â¦)<a class="headerlink" href="#requires-requires-shared" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <code class="docutils literal notranslate"><span class="pre">EXCLUSIVE_LOCKS_REQUIRED</span></code>, <code class="docutils literal notranslate"><span class="pre">SHARED_LOCKS_REQUIRED</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">REQUIRES</span></code> is an attribute on functions or methods, which
+declares that the calling thread must have exclusive access to the given
+capabilities. More than one capability may be specified. The capabilities
+must be held on entry to the function, <em>and must still be held on exit</em>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">REQUIRES_SHARED</span></code> is similar, but requires only shared access.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Mutex</span> <span class="n">mu1</span><span class="p">,</span> <span class="n">mu2</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu1</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">b</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu2</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mu1</span><span class="p">,</span> <span class="n">mu2</span><span class="p">)</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="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu1</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">foo</span><span class="p">();</span> <span class="c1">// Warning! Requires mu2.</span>
+ <span class="n">mu1</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="acquire-acquire-shared-release-release-shared">
+<h3>ACQUIRE(â¦), ACQUIRE_SHARED(â¦), RELEASE(â¦), RELEASE_SHARED(â¦)<a class="headerlink" href="#acquire-acquire-shared-release-release-shared" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <code class="docutils literal notranslate"><span class="pre">EXCLUSIVE_LOCK_FUNCTION</span></code>, <code class="docutils literal notranslate"><span class="pre">SHARED_LOCK_FUNCTION</span></code>,
+<code class="docutils literal notranslate"><span class="pre">UNLOCK_FUNCTION</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">ACQUIRE</span></code> is an attribute on functions or methods, which
+declares that the function acquires a capability, but does not release it. The
+caller must not hold the given capability on entry, and it will hold the
+capability on exit. <code class="docutils literal notranslate"><span class="pre">ACQUIRE_SHARED</span></code> is similar.</p>
+<p><code class="docutils literal notranslate"><span class="pre">RELEASE</span></code> and <code class="docutils literal notranslate"><span class="pre">RELEASE_SHARED</span></code> declare that the function releases the given
+capability. The caller must hold the capability on entry, and will no longer
+hold it on exit. It does not matter whether the given capability is shared or
+exclusive.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="n">MyClass</span> <span class="n">myObject</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">lockAndInit</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">myObject</span><span class="p">.</span><span class="n">init</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">cleanupAndUnlock</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">myObject</span><span class="p">.</span><span class="n">cleanup</span><span class="p">();</span>
+<span class="p">}</span> <span class="c1">// Warning! Need to unlock mu.</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">lockAndInit</span><span class="p">();</span>
+ <span class="n">myObject</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+ <span class="n">cleanupAndUnlock</span><span class="p">();</span>
+ <span class="n">myObject</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span> <span class="c1">// Warning, mu is not locked.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If no argument is passed to <code class="docutils literal notranslate"><span class="pre">ACQUIRE</span></code> or <code class="docutils literal notranslate"><span class="pre">RELEASE</span></code>, then the argument is
+assumed to be <code class="docutils literal notranslate"><span class="pre">this</span></code>, and the analysis will not check the body of the
+function. This pattern is intended for use by classes which hide locking
+details behind an abstract interface. For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">CAPABILITY</span><span class="p">(</span><span class="s">"mutex"</span><span class="p">)</span> <span class="n">Container</span> <span class="p">{</span>
+<span class="k">private</span><span class="o">:</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+ <span class="n">T</span><span class="o">*</span> <span class="n">data</span><span class="p">;</span>
+
+<span class="k">public</span><span class="o">:</span>
+ <span class="c1">// Hide mu from public interface.</span>
+ <span class="kt">void</span> <span class="n">Lock</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">()</span> <span class="p">{</span> <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span> <span class="p">}</span>
+ <span class="kt">void</span> <span class="n">Unlock</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">()</span> <span class="p">{</span> <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span> <span class="p">}</span>
+
+ <span class="n">T</span><span class="o">&</span> <span class="n">getElem</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">return</span> <span class="n">data</span><span class="p">[</span><span class="n">i</span><span class="p">];</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">Container</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">c</span><span class="p">;</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">c</span><span class="p">.</span><span class="n">getElem</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="excludes">
+<h3>EXCLUDES(â¦)<a class="headerlink" href="#excludes" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <code class="docutils literal notranslate"><span class="pre">LOCKS_EXCLUDED</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">EXCLUDES</span></code> is an attribute on functions or methods, which declares that
+the caller must <em>not</em> hold the given capabilities. This annotation is
+used to prevent deadlock. Many mutex implementations are not re-entrant, so
+deadlock can occur if the function acquires the mutex a second time.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">clear</span><span class="p">()</span> <span class="n">EXCLUDES</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</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="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="nf">reset</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">clear</span><span class="p">();</span> <span class="c1">// Warning! Caller cannot hold 'mu'.</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Unlike <code class="docutils literal notranslate"><span class="pre">REQUIRES</span></code>, <code class="docutils literal notranslate"><span class="pre">EXCLUDES</span></code> is optional. The analysis will not issue a
+warning if the attribute is missing, which can lead to false negatives in some
+cases. This issue is discussed further in <a class="reference internal" href="#negative"><span class="std std-ref">Negative Capabilities</span></a>.</p>
+</div>
+<div class="section" id="no-thread-safety-analysis">
+<h3>NO_THREAD_SAFETY_ANALYSIS<a class="headerlink" href="#no-thread-safety-analysis" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></code> is an attribute on functions or methods, which
+turns off thread safety checking for that method. It provides an escape hatch
+for functions which are either (1) deliberately thread-unsafe, or (2) are
+thread-safe, but too complicated for the analysis to understand. Reasons for
+(2) will be described in the <a class="reference internal" href="#limitations"><span class="std std-ref">Known Limitations</span></a>, below.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Counter</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="nf">unsafeIncrement</span><span class="p">()</span> <span class="n">NO_THREAD_SAFETY_ANALYSIS</span> <span class="p">{</span> <span class="n">a</span><span class="o">++</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Unlike the other attributes, NO_THREAD_SAFETY_ANALYSIS is not part of the
+interface of a function, and should thus be placed on the function definition
+(in the <code class="docutils literal notranslate"><span class="pre">.cc</span></code> or <code class="docutils literal notranslate"><span class="pre">.cpp</span></code> file) rather than on the function declaration
+(in the header).</p>
+</div>
+<div class="section" id="return-capability-c">
+<h3>RETURN_CAPABILITY(c)<a class="headerlink" href="#return-capability-c" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <code class="docutils literal notranslate"><span class="pre">LOCK_RETURNED</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">RETURN_CAPABILITY</span></code> is an attribute on functions or methods, which declares
+that the function returns a reference to the given capability. It is used to
+annotate getter methods that return mutexes.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="k">private</span><span class="o">:</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">a</span> <span class="nf">GUARDED_BY</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="n">getMu</span><span class="p">()</span> <span class="n">RETURN_CAPABILITY</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="o">&</span><span class="n">mu</span><span class="p">;</span> <span class="p">}</span>
+
+ <span class="c1">// analysis knows that getMu() == mu</span>
+ <span class="kt">void</span> <span class="n">clear</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">getMu</span><span class="p">())</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="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="acquired-before-acquired-after">
+<h3>ACQUIRED_BEFORE(â¦), ACQUIRED_AFTER(â¦)<a class="headerlink" href="#acquired-before-acquired-after" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">ACQUIRED_BEFORE</span></code> and <code class="docutils literal notranslate"><span class="pre">ACQUIRED_AFTER</span></code> are attributes on member
+declarations, specifically declarations of mutexes or other capabilities.
+These declarations enforce a particular order in which the mutexes must be
+acquired, in order to prevent deadlock.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Mutex</span> <span class="n">m1</span><span class="p">;</span>
+<span class="n">Mutex</span> <span class="n">m2</span> <span class="nf">ACQUIRED_AFTER</span><span class="p">(</span><span class="n">m1</span><span class="p">);</span>
+
+<span class="c1">// Alternative declaration</span>
+<span class="c1">// Mutex m2;</span>
+<span class="c1">// Mutex m1 ACQUIRED_BEFORE(m2);</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">m2</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">m1</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span> <span class="c1">// Warning! m2 must be acquired after m1.</span>
+ <span class="n">m1</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="n">m2</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="capability-string">
+<h3>CAPABILITY(<string>)<a class="headerlink" href="#capability-string" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <code class="docutils literal notranslate"><span class="pre">LOCKABLE</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">CAPABILITY</span></code> is an attribute on classes, which specifies that objects of the
+class can be used as a capability. The string argument specifies the kind of
+capability in error messages, e.g. <code class="docutils literal notranslate"><span class="pre">"mutex"</span></code>. See the <code class="docutils literal notranslate"><span class="pre">Container</span></code> example
+given above, or the <code class="docutils literal notranslate"><span class="pre">Mutex</span></code> class in <a class="reference internal" href="#mutexheader"><span class="std std-ref">mutex.h</span></a>.</p>
+</div>
+<div class="section" id="scoped-capability">
+<h3>SCOPED_CAPABILITY<a class="headerlink" href="#scoped-capability" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously</em>: <code class="docutils literal notranslate"><span class="pre">SCOPED_LOCKABLE</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">SCOPED_CAPABILITY</span></code> is an attribute on classes that implement RAII-style
+locking, in which a capability is acquired in the constructor, and released in
+the destructor. Such classes require special handling because the constructor
+and destructor refer to the capability via different names; see the
+<code class="docutils literal notranslate"><span class="pre">MutexLocker</span></code> class in <a class="reference internal" href="#mutexheader"><span class="std std-ref">mutex.h</span></a>, below.</p>
+</div>
+<div class="section" id="try-acquire-bool-try-acquire-shared-bool">
+<h3>TRY_ACQUIRE(<bool>, â¦), TRY_ACQUIRE_SHARED(<bool>, â¦)<a class="headerlink" href="#try-acquire-bool-try-acquire-shared-bool" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously:</em> <code class="docutils literal notranslate"><span class="pre">EXCLUSIVE_TRYLOCK_FUNCTION</span></code>, <code class="docutils literal notranslate"><span class="pre">SHARED_TRYLOCK_FUNCTION</span></code></p>
+<p>These are attributes on a function or method that tries to acquire the given
+capability, and returns a boolean value indicating success or failure.
+The first argument must be <code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code>, to specify which return value
+indicates success, and the remaining arguments are interpreted in the same way
+as <code class="docutils literal notranslate"><span class="pre">ACQUIRE</span></code>. See <a class="reference internal" href="#mutexheader"><span class="std std-ref">mutex.h</span></a>, below, for example uses.</p>
+</div>
+<div class="section" id="assert-capability-and-assert-shared-capability">
+<h3>ASSERT_CAPABILITY(â¦) and ASSERT_SHARED_CAPABILITY(â¦)<a class="headerlink" href="#assert-capability-and-assert-shared-capability" title="Permalink to this headline">¶</a></h3>
+<p><em>Previously:</em> <code class="docutils literal notranslate"><span class="pre">ASSERT_EXCLUSIVE_LOCK</span></code>, <code class="docutils literal notranslate"><span class="pre">ASSERT_SHARED_LOCK</span></code></p>
+<p>These are attributes on a function or method that does a run-time test to see
+whether the calling thread holds the given capability. The function is assumed
+to fail (no return) if the capability is not held. See <a class="reference internal" href="#mutexheader"><span class="std std-ref">mutex.h</span></a>,
+below, for example uses.</p>
+</div>
+<div class="section" id="guarded-var-and-pt-guarded-var">
+<h3>GUARDED_VAR and PT_GUARDED_VAR<a class="headerlink" href="#guarded-var-and-pt-guarded-var" title="Permalink to this headline">¶</a></h3>
+<p>Use of these attributes has been deprecated.</p>
+</div>
+<div class="section" id="warning-flags">
+<h3>Warning flags<a class="headerlink" href="#warning-flags" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-Wthread-safety</span></code>: Umbrella flag which turns on the following three:<ul>
+<li><code class="docutils literal notranslate"><span class="pre">-Wthread-safety-attributes</span></code>: Sanity checks on attribute syntax.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-Wthread-safety-analysis</span></code>: The core analysis.</li>
+<li><dl class="first docutils">
+<dt><code class="docutils literal notranslate"><span class="pre">-Wthread-safety-precise</span></code>: Requires that mutex expressions match precisely.</dt>
+<dd>This warning can be disabled for code which has a lot of aliases.</dd>
+</dl>
+</li>
+<li><code class="docutils literal notranslate"><span class="pre">-Wthread-safety-reference</span></code>: Checks when guarded members are passed by reference.</li>
+</ul>
+</li>
+</ul>
+<p><a class="reference internal" href="#negative"><span class="std std-ref">Negative Capabilities</span></a> are an experimental feature, which are enabled with:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-Wthread-safety-negative</span></code>: Negative capabilities. Off by default.</li>
+</ul>
+<p>When new features and checks are added to the analysis, they can often introduce
+additional warnings. Those warnings are initially released as <em>beta</em> warnings
+for a period of time, after which they are migrated into the standard analysis.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-Wthread-safety-beta</span></code>: New features. Off by default.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="negative-capabilities">
+<span id="negative"></span><h2>Negative Capabilities<a class="headerlink" href="#negative-capabilities" title="Permalink to this headline">¶</a></h2>
+<p>Thread Safety Analysis is designed to prevent both race conditions and
+deadlock. The GUARDED_BY and REQUIRES attributes prevent race conditions, by
+ensuring that a capability is held before reading or writing to guarded data,
+and the EXCLUDES attribute prevents deadlock, by making sure that a mutex is
+<em>not</em> held.</p>
+<p>However, EXCLUDES is an optional attribute, and does not provide the same
+safety guarantee as REQUIRES. In particular:</p>
+<blockquote>
+<div><ul class="simple">
+<li>A function which acquires a capability does not have to exclude it.</li>
+<li>A function which calls a function that excludes a capability does not
+have transitively exclude that capability.</li>
+</ul>
+</div></blockquote>
+<p>As a result, EXCLUDES can easily produce false negatives:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+ <span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">bar</span><span class="p">();</span> <span class="c1">// No warning.</span>
+ <span class="n">baz</span><span class="p">();</span> <span class="c1">// No warning.</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span> <span class="c1">// No warning. (Should have EXCLUDES(mu)).</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="c1">// ...</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">baz</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">bif</span><span class="p">();</span> <span class="c1">// No warning. (Should have EXCLUDES(mu)).</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">bif</span><span class="p">()</span> <span class="n">EXCLUDES</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Negative requirements are an alternative EXCLUDES that provide
+a stronger safety guarantee. A negative requirement uses the REQUIRES
+attribute, in conjunction with the <code class="docutils literal notranslate"><span class="pre">!</span></code> operator, to indicate that a capability
+should <em>not</em> be held.</p>
+<p>For example, using <code class="docutils literal notranslate"><span class="pre">REQUIRES(!mu)</span></code> instead of <code class="docutils literal notranslate"><span class="pre">EXCLUDES(mu)</span></code> will produce
+the appropriate warnings:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">FooNeg</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+ <span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="o">!</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="c1">// foo() now requires !mu.</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">bar</span><span class="p">();</span>
+ <span class="n">baz</span><span class="p">();</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span> <span class="c1">// WARNING! Missing REQUIRES(!mu).</span>
+ <span class="c1">// ...</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">baz</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">bif</span><span class="p">();</span> <span class="c1">// WARNING! Missing REQUIRES(!mu).</span>
+ <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="nf">bif</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="o">!</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Negative requirements are an experimental feature which is off by default,
+because it will produce many warnings in existing code. It can be enabled
+by passing <code class="docutils literal notranslate"><span class="pre">-Wthread-safety-negative</span></code>.</p>
+</div>
+<div class="section" id="frequently-asked-questions">
+<span id="faq"></span><h2>Frequently Asked Questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">¶</a></h2>
+<ol class="upperalpha simple" start="17">
+<li>Should I put attributes in the header file, or in the .cc/.cpp/.cxx file?</li>
+</ol>
+<p>(A) Attributes are part of the formal interface of a function, and should
+always go in the header, where they are visible to anything that includes
+the header. Attributes in the .cpp file are not visible outside of the
+immediate translation unit, which leads to false negatives and false positives.</p>
+<ol class="upperalpha simple" start="17">
+<li>â<em>Mutex is not locked on every path through here?</em>â What does that mean?</li>
+</ol>
+<ol class="upperalpha simple">
+<li>See <a class="reference internal" href="#conditional-locks"><span class="std std-ref">No conditionally held locks.</span></a>, below.</li>
+</ol>
+</div>
+<div class="section" id="known-limitations">
+<span id="limitations"></span><h2>Known Limitations<a class="headerlink" href="#known-limitations" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="lexical-scope">
+<h3>Lexical scope<a class="headerlink" href="#lexical-scope" title="Permalink to this headline">¶</a></h3>
+<p>Thread safety attributes contain ordinary C++ expressions, and thus follow
+ordinary C++ scoping rules. In particular, this means that mutexes and other
+capabilities must be declared before they can be used in an attribute.
+Use-before-declaration is okay within a single class, because attributes are
+parsed at the same time as method bodies. (C++ delays parsing of method bodies
+until the end of the class.) However, use-before-declaration is not allowed
+between classes, as illustrated below.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Foo</span><span class="p">;</span>
+
+<span class="k">class</span> <span class="nc">Bar</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">bar</span><span class="p">(</span><span class="n">Foo</span><span class="o">*</span> <span class="n">f</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">f</span><span class="o">-></span><span class="n">mu</span><span class="p">);</span> <span class="c1">// Error: mu undeclared.</span>
+<span class="p">};</span>
+
+<span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="private-mutexes">
+<h3>Private Mutexes<a class="headerlink" href="#private-mutexes" title="Permalink to this headline">¶</a></h3>
+<p>Good software engineering practice dictates that mutexes should be private
+members, because the locking mechanism used by a thread-safe class is part of
+its internal implementation. However, private mutexes can sometimes leak into
+the public interface of a class.
+Thread safety attributes follow normal C++ access restrictions, so if <code class="docutils literal notranslate"><span class="pre">mu</span></code>
+is a private member of <code class="docutils literal notranslate"><span class="pre">c</span></code>, then it is an error to write <code class="docutils literal notranslate"><span class="pre">c.mu</span></code> in an
+attribute.</p>
+<p>One workaround is to (ab)use the <code class="docutils literal notranslate"><span class="pre">RETURN_CAPABILITY</span></code> attribute to provide a
+public <em>name</em> for a private mutex, without actually exposing the underlying
+mutex. For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="k">private</span><span class="o">:</span>
+ <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+<span class="k">public</span><span class="o">:</span>
+ <span class="c1">// For thread safety analysis only. Does not actually return mu.</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="n">getMu</span><span class="p">()</span> <span class="n">RETURN_CAPABILITY</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="mi">0</span><span class="p">;</span> <span class="p">}</span>
+
+ <span class="kt">void</span> <span class="n">doSomething</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mu</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="kt">void</span> <span class="nf">doSomethingTwice</span><span class="p">(</span><span class="n">MyClass</span><span class="o">&</span> <span class="n">c</span><span class="p">)</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">c</span><span class="p">.</span><span class="n">getMu</span><span class="p">())</span> <span class="p">{</span>
+ <span class="c1">// The analysis thinks that c.getMu() == c.mu</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+ <span class="n">c</span><span class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In the above example, <code class="docutils literal notranslate"><span class="pre">doSomethingTwice()</span></code> is an external routine that
+requires <code class="docutils literal notranslate"><span class="pre">c.mu</span></code> to be locked, which cannot be declared directly because <code class="docutils literal notranslate"><span class="pre">mu</span></code>
+is private. This pattern is discouraged because it
+violates encapsulation, but it is sometimes necessary, especially when adding
+annotations to an existing code base. The workaround is to define <code class="docutils literal notranslate"><span class="pre">getMu()</span></code>
+as a fake getter method, which is provided only for the benefit of thread
+safety analysis.</p>
+</div>
+<div class="section" id="no-conditionally-held-locks">
+<span id="conditional-locks"></span><h3>No conditionally held locks.<a class="headerlink" href="#no-conditionally-held-locks" title="Permalink to this headline">¶</a></h3>
+<p>The analysis must be able to determine whether a lock is held, or not held, at
+every program point. Thus, sections of code where a lock <em>might be held</em> will
+generate spurious warnings (false positives). For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="kt">bool</span> <span class="n">b</span> <span class="o">=</span> <span class="n">needsToLock</span><span class="p">();</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="p">...</span> <span class="c1">// Warning! Mutex 'mu' is not held on every path through here.</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">mu</span><span class="p">.</span><span class="n">Unlock</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="no-checking-inside-constructors-and-destructors">
+<h3>No checking inside constructors and destructors.<a class="headerlink" href="#no-checking-inside-constructors-and-destructors" title="Permalink to this headline">¶</a></h3>
+<p>The analysis currently does not do any checking inside constructors or
+destructors. In other words, every constructor and destructor is treated as
+if it was annotated with <code class="docutils literal notranslate"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></code>.
+The reason for this is that during initialization, only one thread typically
+has access to the object which is being initialized, and it is thus safe (and
+common practice) to initialize guarded members without acquiring any locks.
+The same is true of destructors.</p>
+<p>Ideally, the analysis would allow initialization of guarded members inside the
+object being initialized or destroyed, while still enforcing the usual access
+restrictions on everything else. However, this is difficult to enforce in
+practice, because in complex pointer-based data structures, it is hard to
+determine what data is owned by the enclosing object.</p>
+</div>
+<div class="section" id="no-inlining">
+<h3>No inlining.<a class="headerlink" href="#no-inlining" title="Permalink to this headline">¶</a></h3>
+<p>Thread safety analysis is strictly intra-procedural, just like ordinary type
+checking. It relies only on the declared attributes of a function, and will
+not attempt to inline any method calls. As a result, code such as the
+following will not work:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span><span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span>
+<span class="k">class</span> <span class="nc">AutoCleanup</span> <span class="p">{</span>
+ <span class="n">T</span><span class="o">*</span> <span class="n">object</span><span class="p">;</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="n">T</span><span class="o">::*</span><span class="n">mp</span><span class="p">)();</span>
+
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">AutoCleanup</span><span class="p">(</span><span class="n">T</span><span class="o">*</span> <span class="n">obj</span><span class="p">,</span> <span class="kt">void</span> <span class="p">(</span><span class="n">T</span><span class="o">::*</span><span class="n">imp</span><span class="p">)())</span> <span class="o">:</span> <span class="n">object</span><span class="p">(</span><span class="n">obj</span><span class="p">),</span> <span class="n">mp</span><span class="p">(</span><span class="n">imp</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
+ <span class="o">~</span><span class="n">AutoCleanup</span><span class="p">()</span> <span class="p">{</span> <span class="p">(</span><span class="n">object</span><span class="o">->*</span><span class="n">mp</span><span class="p">)();</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="p">.</span><span class="n">Lock</span><span class="p">();</span>
+ <span class="n">AutoCleanup</span><span class="o"><</span><span class="n">Mutex</span><span class="o">></span><span class="p">(</span><span class="o">&</span><span class="n">mu</span><span class="p">,</span> <span class="o">&</span><span class="n">Mutex</span><span class="o">::</span><span class="n">Unlock</span><span class="p">);</span>
+ <span class="c1">// ...</span>
+<span class="p">}</span> <span class="c1">// Warning, mu is not unlocked.</span>
+</pre></div>
+</div>
+<p>In this case, the destructor of <code class="docutils literal notranslate"><span class="pre">Autocleanup</span></code> calls <code class="docutils literal notranslate"><span class="pre">mu.Unlock()</span></code>, so
+the warning is bogus. However,
+thread safety analysis cannot see the unlock, because it does not attempt to
+inline the destructor. Moreover, there is no way to annotate the destructor,
+because the destructor is calling a function that is not statically known.
+This pattern is simply not supported.</p>
+</div>
+<div class="section" id="no-alias-analysis">
+<h3>No alias analysis.<a class="headerlink" href="#no-alias-analysis" title="Permalink to this headline">¶</a></h3>
+<p>The analysis currently does not track pointer aliases. Thus, there can be
+false positives if two pointers both point to the same mutex.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MutexUnlocker</span> <span class="p">{</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="n">mu</span><span class="p">;</span>
+
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">MutexUnlocker</span><span class="p">(</span><span class="n">Mutex</span><span class="o">*</span> <span class="n">m</span><span class="p">)</span> <span class="n">RELEASE</span><span class="p">(</span><span class="n">m</span><span class="p">)</span> <span class="o">:</span> <span class="n">mu</span><span class="p">(</span><span class="n">m</span><span class="p">)</span> <span class="p">{</span> <span class="n">mu</span><span class="o">-></span><span class="n">Unlock</span><span class="p">();</span> <span class="p">}</span>
+ <span class="o">~</span><span class="n">MutexUnlocker</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span> <span class="n">mu</span><span class="o">-></span><span class="n">Lock</span><span class="p">();</span> <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="n">Mutex</span> <span class="n">mutex</span><span class="p">;</span>
+<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="n">REQUIRES</span><span class="p">(</span><span class="n">mutex</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">{</span>
+ <span class="n">MutexUnlocker</span> <span class="n">munl</span><span class="p">(</span><span class="o">&</span><span class="n">mutex</span><span class="p">);</span> <span class="c1">// unlocks mutex</span>
+ <span class="n">doSomeIO</span><span class="p">();</span>
+ <span class="p">}</span> <span class="c1">// Warning: locks munl.mu</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The MutexUnlocker class is intended to be the dual of the MutexLocker class,
+defined in <a class="reference internal" href="#mutexheader"><span class="std std-ref">mutex.h</span></a>. However, it doesnât work because the analysis
+doesnât know that munl.mu == mutex. The SCOPED_CAPABILITY attribute handles
+aliasing for MutexLocker, but does so only for that particular pattern.</p>
+</div>
+<div class="section" id="acquired-before-and-acquired-after-are-currently-unimplemented">
+<h3>ACQUIRED_BEFORE(â¦) and ACQUIRED_AFTER(â¦) are currently unimplemented.<a class="headerlink" href="#acquired-before-and-acquired-after-are-currently-unimplemented" title="Permalink to this headline">¶</a></h3>
+<p>To be fixed in a future update.</p>
+</div>
+</div>
+<div class="section" id="mutex-h">
+<span id="mutexheader"></span><h2>mutex.h<a class="headerlink" href="#mutex-h" title="Permalink to this headline">¶</a></h2>
+<p>Thread safety analysis can be used with any threading library, but it does
+require that the threading API be wrapped in classes and methods which have the
+appropriate annotations. The following code provides <code class="docutils literal notranslate"><span class="pre">mutex.h</span></code> as an example;
+these methods should be filled in to call the appropriate underlying
+implementation.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#ifndef THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+<span class="cp">#define THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+
+<span class="c1">// Enable thread safety attributes only with clang.</span>
+<span class="c1">// The attributes can be safely erased when compiling with other compilers.</span>
+<span class="cp">#if defined(__clang__) && (!defined(SWIG))</span>
+<span class="cp">#define THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x))</span>
+<span class="cp">#else</span>
+<span class="cp">#define THREAD_ANNOTATION_ATTRIBUTE__(x) </span><span class="c1">// no-op</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#define CAPABILITY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(capability(x))</span>
+
+<span class="cp">#define SCOPED_CAPABILITY \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)</span>
+
+<span class="cp">#define GUARDED_BY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x))</span>
+
+<span class="cp">#define PT_GUARDED_BY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x))</span>
+
+<span class="cp">#define ACQUIRED_BEFORE(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(__VA_ARGS__))</span>
+
+<span class="cp">#define ACQUIRED_AFTER(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(__VA_ARGS__))</span>
+
+<span class="cp">#define REQUIRES(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define REQUIRES_SHARED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define ACQUIRE(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define ACQUIRE_SHARED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define RELEASE(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(release_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define RELEASE_SHARED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define TRY_ACQUIRE(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define TRY_ACQUIRE_SHARED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(__VA_ARGS__))</span>
+
+<span class="cp">#define EXCLUDES(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))</span>
+
+<span class="cp">#define ASSERT_CAPABILITY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x))</span>
+
+<span class="cp">#define ASSERT_SHARED_CAPABILITY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x))</span>
+
+<span class="cp">#define RETURN_CAPABILITY(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))</span>
+
+<span class="cp">#define NO_THREAD_SAFETY_ANALYSIS \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis)</span>
+
+
+<span class="c1">// Defines an annotated interface for mutexes.</span>
+<span class="c1">// These methods can be implemented to use any internal mutex implementation.</span>
+<span class="k">class</span> <span class="nf">CAPABILITY</span><span class="p">(</span><span class="s">"mutex"</span><span class="p">)</span> <span class="n">Mutex</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="c1">// Acquire/lock this mutex exclusively. Only one thread can have exclusive</span>
+ <span class="c1">// access at any one time. Write operations to guarded data require an</span>
+ <span class="c1">// exclusive lock.</span>
+ <span class="kt">void</span> <span class="n">Lock</span><span class="p">()</span> <span class="n">ACQUIRE</span><span class="p">();</span>
+
+ <span class="c1">// Acquire/lock this mutex for read operations, which require only a shared</span>
+ <span class="c1">// lock. This assumes a multiple-reader, single writer semantics. Multiple</span>
+ <span class="c1">// threads may acquire the mutex simultaneously as readers, but a writer</span>
+ <span class="c1">// must wait for all of them to release the mutex before it can acquire it</span>
+ <span class="c1">// exclusively.</span>
+ <span class="kt">void</span> <span class="n">ReaderLock</span><span class="p">()</span> <span class="n">ACQUIRE_SHARED</span><span class="p">();</span>
+
+ <span class="c1">// Release/unlock an exclusive mutex.</span>
+ <span class="kt">void</span> <span class="n">Unlock</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">();</span>
+
+ <span class="c1">// Release/unlock a shared mutex.</span>
+ <span class="kt">void</span> <span class="n">ReaderUnlock</span><span class="p">()</span> <span class="n">RELEASE_SHARED</span><span class="p">();</span>
+
+ <span class="c1">// Try to acquire the mutex. Returns true on success, and false on failure.</span>
+ <span class="kt">bool</span> <span class="n">TryLock</span><span class="p">()</span> <span class="n">TRY_ACQUIRE</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span>
+
+ <span class="c1">// Try to acquire the mutex for read operations.</span>
+ <span class="kt">bool</span> <span class="n">ReaderTryLock</span><span class="p">()</span> <span class="n">TRY_ACQUIRE_SHARED</span><span class="p">(</span><span class="nb">true</span><span class="p">);</span>
+
+ <span class="c1">// Assert that this mutex is currently held by the calling thread.</span>
+ <span class="kt">void</span> <span class="n">AssertHeld</span><span class="p">()</span> <span class="n">ASSERT_CAPABILITY</span><span class="p">(</span><span class="k">this</span><span class="p">);</span>
+
+ <span class="c1">// Assert that is mutex is currently held for read operations.</span>
+ <span class="kt">void</span> <span class="n">AssertReaderHeld</span><span class="p">()</span> <span class="n">ASSERT_SHARED_CAPABILITY</span><span class="p">(</span><span class="k">this</span><span class="p">);</span>
+
+ <span class="c1">// For negative capabilities.</span>
+ <span class="k">const</span> <span class="n">Mutex</span><span class="o">&</span> <span class="k">operator</span><span class="o">!</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="o">*</span><span class="k">this</span><span class="p">;</span> <span class="p">}</span>
+<span class="p">};</span>
+
+
+<span class="c1">// MutexLocker is an RAII class that acquires a mutex in its constructor, and</span>
+<span class="c1">// releases it in its destructor.</span>
+<span class="k">class</span> <span class="nc">SCOPED_CAPABILITY</span> <span class="n">MutexLocker</span> <span class="p">{</span>
+<span class="k">private</span><span class="o">:</span>
+ <span class="n">Mutex</span><span class="o">*</span> <span class="n">mut</span><span class="p">;</span>
+
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">MutexLocker</span><span class="p">(</span><span class="n">Mutex</span> <span class="o">*</span><span class="n">mu</span><span class="p">)</span> <span class="n">ACQUIRE</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="o">:</span> <span class="n">mut</span><span class="p">(</span><span class="n">mu</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">mu</span><span class="o">-></span><span class="n">Lock</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="o">~</span><span class="n">MutexLocker</span><span class="p">()</span> <span class="n">RELEASE</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">mut</span><span class="o">-></span><span class="n">Unlock</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+
+<span class="cp">#ifdef USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES</span>
+<span class="c1">// The original version of thread safety analysis the following attribute</span>
+<span class="c1">// definitions. These use a lock-based terminology. They are still in use</span>
+<span class="c1">// by existing thread safety code, and will continue to be supported.</span>
+
+<span class="c1">// Deprecated.</span>
+<span class="cp">#define PT_GUARDED_VAR \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_var)</span>
+
+<span class="c1">// Deprecated.</span>
+<span class="cp">#define GUARDED_VAR \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(guarded_var)</span>
+
+<span class="c1">// Replaced by REQUIRES</span>
+<span class="cp">#define EXCLUSIVE_LOCKS_REQUIRED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(exclusive_locks_required(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by REQUIRES_SHARED</span>
+<span class="cp">#define SHARED_LOCKS_REQUIRED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(shared_locks_required(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by CAPABILITY</span>
+<span class="cp">#define LOCKABLE \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(lockable)</span>
+
+<span class="c1">// Replaced by SCOPED_CAPABILITY</span>
+<span class="cp">#define SCOPED_LOCKABLE \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable)</span>
+
+<span class="c1">// Replaced by ACQUIRE</span>
+<span class="cp">#define EXCLUSIVE_LOCK_FUNCTION(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(exclusive_lock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by ACQUIRE_SHARED</span>
+<span class="cp">#define SHARED_LOCK_FUNCTION(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(shared_lock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by RELEASE and RELEASE_SHARED</span>
+<span class="cp">#define UNLOCK_FUNCTION(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(unlock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by TRY_ACQUIRE</span>
+<span class="cp">#define EXCLUSIVE_TRYLOCK_FUNCTION(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(exclusive_trylock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by TRY_ACQUIRE_SHARED</span>
+<span class="cp">#define SHARED_TRYLOCK_FUNCTION(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(shared_trylock_function(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by ASSERT_CAPABILITY</span>
+<span class="cp">#define ASSERT_EXCLUSIVE_LOCK(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(assert_exclusive_lock(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by ASSERT_SHARED_CAPABILITY</span>
+<span class="cp">#define ASSERT_SHARED_LOCK(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_lock(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by EXCLUDE_CAPABILITY.</span>
+<span class="cp">#define LOCKS_EXCLUDED(...) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(__VA_ARGS__))</span>
+
+<span class="c1">// Replaced by RETURN_CAPABILITY</span>
+<span class="cp">#define LOCK_RETURNED(x) \</span>
+<span class="cp"> THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x))</span>
+
+<span class="cp">#endif </span><span class="c1">// USE_LOCK_STYLE_THREAD_SAFETY_ATTRIBUTES</span>
+
+<span class="cp">#endif </span><span class="c1">// THREAD_SAFETY_ANALYSIS_MUTEX_H</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="analyzer/developer-docs/RegionStore.html">3.5. Region Store</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="AddressSanitizer.html">AddressSanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/ThreadSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/ThreadSanitizer.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/ThreadSanitizer.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/ThreadSanitizer.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,189 @@
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>ThreadSanitizer — Clang 9 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="MemorySanitizer" href="MemorySanitizer.html" />
+ <link rel="prev" title="AddressSanitizer" href="AddressSanitizer.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>ThreadSanitizer</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="AddressSanitizer.html">AddressSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="MemorySanitizer.html">MemorySanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="threadsanitizer">
+<h1>ThreadSanitizer<a class="headerlink" href="#threadsanitizer" 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>ThreadSanitizer is a tool that detects data races. It consists of a compiler
+instrumentation module and a run-time library. Typical slowdown introduced by
+ThreadSanitizer is about <strong>5x-15x</strong>. Typical memory overhead introduced by
+ThreadSanitizer is about <strong>5x-10x</strong>.</p>
+</div>
+<div class="section" id="how-to-build">
+<h2>How to build<a class="headerlink" href="#how-to-build" title="Permalink to this headline">¶</a></h2>
+<p>Build LLVM/Clang with <a class="reference external" href="https://llvm.org/docs/CMake.html">CMake</a>.</p>
+</div>
+<div class="section" id="supported-platforms">
+<h2>Supported Platforms<a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer is supported on the following OS:</p>
+<ul class="simple">
+<li>Android aarch64, x86_64</li>
+<li>Darwin arm64, x86_64</li>
+<li>FreeBSD</li>
+<li>Linux aarch64, x86_64, powerpc64, powerpc64le</li>
+<li>NetBSD</li>
+</ul>
+<p>Support for other 64-bit architectures is possible, contributions are welcome.
+Support for 32-bit platforms is problematic and is not planned.</p>
+</div>
+<div class="section" id="usage">
+<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>Simply compile and link your program with <code class="docutils literal notranslate"><span class="pre">-fsanitize=thread</span></code>. To get a
+reasonable performance add <code class="docutils literal notranslate"><span class="pre">-O1</span></code> or higher. Use <code class="docutils literal notranslate"><span class="pre">-g</span></code> to get file names
+and line numbers in the warning messages.</p>
+<p>Example:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> cat projects/compiler-rt/lib/tsan/lit_tests/tiny_race.c
+<span class="gp">#</span>include <pthread.h>
+<span class="go">int Global;</span>
+<span class="go">void *Thread1(void *x) {</span>
+<span class="go"> Global = 42;</span>
+<span class="go"> return x;</span>
+<span class="go">}</span>
+<span class="go">int main() {</span>
+<span class="go"> pthread_t t;</span>
+<span class="go"> pthread_create(&t, NULL, Thread1, NULL);</span>
+<span class="go"> Global = 43;</span>
+<span class="go"> pthread_join(t, NULL);</span>
+<span class="go"> return Global;</span>
+<span class="go">}</span>
+
+<span class="gp">$</span> clang -fsanitize<span class="o">=</span>thread -g -O1 tiny_race.c
+</pre></div>
+</div>
+<p>If a bug is detected, the program will print an error message to stderr.
+Currently, ThreadSanitizer symbolizes its output using an external
+<code class="docutils literal notranslate"><span class="pre">addr2line</span></code> process (this will be fixed in future).</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>% ./a.out
+WARNING: ThreadSanitizer: data race <span class="o">(</span><span class="nv">pid</span><span class="o">=</span><span class="m">19219</span><span class="o">)</span>
+ Write of size <span class="m">4</span> at 0x7fcf47b21bc0 by thread T1:
+ <span class="c1">#0 Thread1 tiny_race.c:4 (exe+0x00000000a360)</span>
+
+ Previous write of size <span class="m">4</span> at 0x7fcf47b21bc0 by main thread:
+ <span class="c1">#0 main tiny_race.c:10 (exe+0x00000000a3b4)</span>
+
+ Thread T1 <span class="o">(</span>running<span class="o">)</span> created at:
+ <span class="c1">#0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790)</span>
+ <span class="c1">#1 main tiny_race.c:9 (exe+0x00000000a3a4)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="has-feature-thread-sanitizer">
+<h2><code class="docutils literal notranslate"><span class="pre">__has_feature(thread_sanitizer)</span></code><a class="headerlink" href="#has-feature-thread-sanitizer" title="Permalink to this headline">¶</a></h2>
+<p>In some cases one may need to execute different code depending on whether
+ThreadSanitizer is enabled.
+<a class="reference internal" href="LanguageExtensions.html#langext-has-feature-has-extension"><span class="std std-ref">__has_feature</span></a> can be used for
+this purpose.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#if defined(__has_feature)</span>
+<span class="cp"># if __has_feature(thread_sanitizer)</span>
+<span class="c1">// code that builds only under ThreadSanitizer</span>
+<span class="cp"># endif</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-thread">
+<h2><code class="docutils literal notranslate"><span class="pre">__attribute__((no_sanitize("thread")))</span></code><a class="headerlink" href="#attribute-no-sanitize-thread" title="Permalink to this headline">¶</a></h2>
+<p>Some code should not be instrumented by ThreadSanitizer. One may use the
+function attribute <code class="docutils literal notranslate"><span class="pre">no_sanitize("thread")</span></code> to disable instrumentation of plain
+(non-atomic) loads/stores in a particular function. ThreadSanitizer still
+instruments such functions to avoid false positives and provide meaningful stack
+traces. This attribute may not be supported by other compilers, so we suggest
+to use it together with <code class="docutils literal notranslate"><span class="pre">__has_feature(thread_sanitizer)</span></code>.</p>
+</div>
+<div class="section" id="blacklist">
+<h2>Blacklist<a class="headerlink" href="#blacklist" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer supports <code class="docutils literal notranslate"><span class="pre">src</span></code> and <code class="docutils literal notranslate"><span class="pre">fun</span></code> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><span class="doc">Sanitizer special case list</span></a>, that can be used to suppress data race reports
+in the specified source files or functions. Unlike functions marked with
+<code class="docutils literal notranslate"><span class="pre">no_sanitize("thread")</span></code> attribute, blacklisted functions are not instrumented
+at all. This can lead to false positives due to missed synchronization via
+atomic operations and missed stack frames in reports.</p>
+</div>
+<div class="section" id="limitations">
+<h2>Limitations<a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>ThreadSanitizer uses more real memory than a native run. At the default
+settings the memory overhead is 5x plus 1Mb per each thread. Settings with 3x
+(less accurate analysis) and 9x (more accurate analysis) overhead are also
+available.</li>
+<li>ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
+This means that tools like <code class="docutils literal notranslate"><span class="pre">ulimit</span></code> may not work as usually expected.</li>
+<li>Libc/libstdc++ static linking is not supported.</li>
+<li>Non-position-independent executables are not supported. Therefore, the
+<code class="docutils literal notranslate"><span class="pre">fsanitize=thread</span></code> flag will cause Clang to act as though the <code class="docutils literal notranslate"><span class="pre">-fPIE</span></code>
+flag had been supplied if compiling without <code class="docutils literal notranslate"><span class="pre">-fPIC</span></code>, and as though the
+<code class="docutils literal notranslate"><span class="pre">-pie</span></code> flag had been supplied if linking an executable.</li>
+</ul>
+</div>
+<div class="section" id="current-status">
+<h2>Current Status<a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer is in beta stage. It is known to work on large C++ programs
+using pthreads, but we do not promise anything (yet). C++11 threading is
+supported with llvm libc++. The test suite is integrated into CMake build
+and can be run with <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">check-tsan</span></code> command.</p>
+<p>We are actively working on enhancing the tool â stay tuned. Any help,
+especially in the form of minimized standalone tests is more than welcome.</p>
+</div>
+<div class="section" id="more-information">
+<h2>More Information<a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual">https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual</a></p>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="AddressSanitizer.html">AddressSanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="MemorySanitizer.html">MemorySanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/Toolchain.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/Toolchain.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/Toolchain.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/Toolchain.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,371 @@
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Assembling a Complete Toolchain — Clang 9 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Clang Language Extensions" href="LanguageExtensions.html" />
+ <link rel="prev" title="Clang Compiler Userâs Manual" href="UsersManual.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>Assembling a Complete Toolchain</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="UsersManual.html">Clang Compiler Userâs Manual</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LanguageExtensions.html">Clang Language Extensions</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="assembling-a-complete-toolchain">
+<h1>Assembling a Complete Toolchain<a class="headerlink" href="#assembling-a-complete-toolchain" 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="id8">Introduction</a></li>
+<li><a class="reference internal" href="#tools" id="id9">Tools</a><ul>
+<li><a class="reference internal" href="#clang-frontend" id="id10">Clang frontend</a></li>
+<li><a class="reference internal" href="#language-frontends-for-other-languages" id="id11">Language frontends for other languages</a></li>
+<li><a class="reference internal" href="#assembler" id="id12">Assembler</a></li>
+<li><a class="reference internal" href="#linker" id="id13">Linker</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#runtime-libraries" id="id14">Runtime libraries</a><ul>
+<li><a class="reference internal" href="#compiler-runtime" id="id15">Compiler runtime</a></li>
+<li><a class="reference internal" href="#atomics-library" id="id16">Atomics library</a></li>
+<li><a class="reference internal" href="#unwind-library" id="id17">Unwind library</a></li>
+<li><a class="reference internal" href="#sanitizer-runtime" id="id18">Sanitizer runtime</a></li>
+<li><a class="reference internal" href="#c-standard-library" id="id19">C standard library</a></li>
+<li><a class="reference internal" href="#c-abi-library" id="id20">C++ ABI library</a></li>
+<li><a class="reference internal" href="#id6" id="id21">C++ standard library</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id8">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Clang is only one component in a complete tool chain for C family
+programming languages. In order to assemble a complete toolchain,
+additional tools and runtime libraries are required. Clang is designed
+to interoperate with existing tools and libraries for its target
+platforms, and the LLVM project provides alternatives for a number
+of these components.</p>
+<p>This document describes the required and optional components in a
+complete toolchain, where to find them, and the supported versions
+and limitations of each option.</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document currently describes Clang configurations on POSIX-like
+operating systems with the GCC-compatible <code class="docutils literal notranslate"><span class="pre">clang</span></code> driver. When
+targeting Windows with the MSVC-compatible <code class="docutils literal notranslate"><span class="pre">clang-cl</span></code> driver, some
+of the details are different.</p>
+</div>
+</div>
+<div class="section" id="tools">
+<h2><a class="toc-backref" href="#id9">Tools</a><a class="headerlink" href="#tools" title="Permalink to this headline">¶</a></h2>
+<p>A complete compilation of C family programming languages typically
+involves the following pipeline of tools, some of which are omitted
+in some compilations:</p>
+<ul class="simple">
+<li><strong>Preprocessor</strong>: This performs the actions of the C preprocessor:
+expanding #includes and #defines.
+The <code class="docutils literal notranslate"><span class="pre">-E</span></code> flag instructs Clang to stop after this step.</li>
+<li><strong>Parsing</strong>: This parses and semantically analyzes the source language and
+builds a source-level intermediate representation (âASTâ), producing a
+<a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><span class="std std-ref">precompiled header (PCH)</span></a>,
+preamble, or
+<a class="reference internal" href="Modules.html"><span class="doc">precompiled module file (PCM)</span></a>,
+depending on the input.
+The <code class="docutils literal notranslate"><span class="pre">-precompile</span></code> flag instructs Clang to stop after this step. This is
+the default when the input is a header file.</li>
+<li><strong>IR generation</strong>: This converts the source-level intermediate representation
+into an optimizer-specific intermediate representation (IR); for Clang, this
+is LLVM IR.
+The <code class="docutils literal notranslate"><span class="pre">-emit-llvm</span></code> flag instructs Clang to stop after this step. If combined
+with <code class="docutils literal notranslate"><span class="pre">-S</span></code>, Clang will produce textual LLVM IR; otherwise, it will produce
+LLVM IR bitcode.</li>
+<li><strong>Compiler backend</strong>: This converts the intermediate representation
+into target-specific assembly code.
+The <code class="docutils literal notranslate"><span class="pre">-S</span></code> flag instructs Clang to stop after this step.</li>
+<li><strong>Assembler</strong>: This converts target-specific assembly code into
+target-specific machine code object files.
+The <code class="docutils literal notranslate"><span class="pre">-c</span></code> flag instructs Clang to stop after this step.</li>
+<li><strong>Linker</strong>: This combines multiple object files into a single image
+(either a shared object or an executable).</li>
+</ul>
+<p>Clang provides all of these pieces other than the linker. When multiple
+steps are performed by the same tool, it is common for the steps to be
+fused together to avoid creating intermediate files.</p>
+<p>When given an output of one of the above steps as an input, earlier steps
+are skipped (for instance, a <code class="docutils literal notranslate"><span class="pre">.s</span></code> file input will be assembled and linked).</p>
+<p>The Clang driver can be invoked with the <code class="docutils literal notranslate"><span class="pre">-###</span></code> flag (this argument will need
+to be escaped under most shells) to see which commands it would run for the
+above steps, without running them. The <code class="docutils literal notranslate"><span class="pre">-v</span></code> (verbose) flag will print the
+commands in addition to running them.</p>
+<div class="section" id="clang-frontend">
+<h3><a class="toc-backref" href="#id10">Clang frontend</a><a class="headerlink" href="#clang-frontend" title="Permalink to this headline">¶</a></h3>
+<p>The Clang frontend (<code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">-cc1</span></code>) is used to compile C family languages. The
+command-line interface of the frontend is considered to be an implementation
+detail, intentionally has no external documentation, and is subject to change
+without notice.</p>
+</div>
+<div class="section" id="language-frontends-for-other-languages">
+<h3><a class="toc-backref" href="#id11">Language frontends for other languages</a><a class="headerlink" href="#language-frontends-for-other-languages" title="Permalink to this headline">¶</a></h3>
+<p>Clang can be provided with inputs written in non-C-family languages. In such
+cases, an external tool will be used to compile the input. The
+currently-supported languages are:</p>
+<ul class="simple">
+<li>Ada (<code class="docutils literal notranslate"><span class="pre">-x</span> <span class="pre">ada</span></code>, <code class="docutils literal notranslate"><span class="pre">.ad[bs]</span></code>)</li>
+<li>Fortran (<code class="docutils literal notranslate"><span class="pre">-x</span> <span class="pre">f95</span></code>, <code class="docutils literal notranslate"><span class="pre">.f</span></code>, <code class="docutils literal notranslate"><span class="pre">.f9[05]</span></code>, <code class="docutils literal notranslate"><span class="pre">.for</span></code>, <code class="docutils literal notranslate"><span class="pre">.fpp</span></code>, case-insensitive)</li>
+<li>Java (<code class="docutils literal notranslate"><span class="pre">-x</span> <span class="pre">java</span></code>)</li>
+</ul>
+<p>In each case, GCC will be invoked to compile the input.</p>
+</div>
+<div class="section" id="assembler">
+<h3><a class="toc-backref" href="#id12">Assembler</a><a class="headerlink" href="#assembler" title="Permalink to this headline">¶</a></h3>
+<p>Clang can either use LLVMâs integrated assembler or an external system-specific
+tool (for instance, the GNU Assembler on GNU OSes) to produce machine code from
+assembly.
+By default, Clang uses LLVMâs integrated assembler on all targets where it is
+supported. If you wish to use the system assembler instead, use the
+<code class="docutils literal notranslate"><span class="pre">-fno-integrated-as</span></code> option.</p>
+</div>
+<div class="section" id="linker">
+<h3><a class="toc-backref" href="#id13">Linker</a><a class="headerlink" href="#linker" title="Permalink to this headline">¶</a></h3>
+<p>Clang can be configured to use one of several different linkers:</p>
+<ul class="simple">
+<li>GNU ld</li>
+<li>GNU gold</li>
+<li>LLVMâs <a class="reference external" href="https://lld.llvm.org">lld</a></li>
+<li>MSVCâs link.exe</li>
+</ul>
+<p>Link-time optimization is natively supported by lld, and supported via
+a <a class="reference external" href="https://llvm.org/docs/GoldPlugin.html">linker plugin</a> when using gold.</p>
+<p>The default linker varies between targets, and can be overridden via the
+<code class="docutils literal notranslate"><span class="pre">-fuse-ld=<linker</span> <span class="pre">name></span></code> flag.</p>
+</div>
+</div>
+<div class="section" id="runtime-libraries">
+<h2><a class="toc-backref" href="#id14">Runtime libraries</a><a class="headerlink" href="#runtime-libraries" title="Permalink to this headline">¶</a></h2>
+<p>A number of different runtime libraries are required to provide different
+layers of support for C family programs. Clang will implicitly link an
+appropriate implementation of each runtime library, selected based on
+target defaults or explicitly selected by the <code class="docutils literal notranslate"><span class="pre">--rtlib=</span></code> and <code class="docutils literal notranslate"><span class="pre">--stdlib=</span></code>
+flags.</p>
+<p>The set of implicitly-linked libraries depend on the language mode. As a
+consequence, you should use <code class="docutils literal notranslate"><span class="pre">clang++</span></code> when linking C++ programs in order
+to ensure the C++ runtimes are provided.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">There may exist other implementations for these components not described
+below. Please let us know how well those other implementations work with
+Clang so they can be added to this list!</p>
+</div>
+<div class="section" id="compiler-runtime">
+<h3><a class="toc-backref" href="#id15">Compiler runtime</a><a class="headerlink" href="#compiler-runtime" title="Permalink to this headline">¶</a></h3>
+<p>The compiler runtime library provides definitions of functions implicitly
+invoked by the compiler to support operations not natively supported by
+the underlying hardware (for instance, 128-bit integer multiplications),
+and where inline expansion of the operation is deemed unsuitable.</p>
+<p>The default runtime library is target-specific. For targets where GCC is
+the dominant compiler, Clang currently defaults to using libgcc_s. On most
+other targets, compiler-rt is used by default.</p>
+<div class="section" id="compiler-rt-llvm">
+<h4>compiler-rt (LLVM)<a class="headerlink" href="#compiler-rt-llvm" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="https://compiler-rt.llvm.org/">LLVMâs compiler runtime library</a> provides a
+complete set of runtime library functions containing all functions that
+Clang will implicitly call, in <code class="docutils literal notranslate"><span class="pre">libclang_rt.builtins.<arch>.a</span></code>.</p>
+<p>You can instruct Clang to use compiler-rt with the <code class="docutils literal notranslate"><span class="pre">--rtlib=compiler-rt</span></code> flag.
+This is not supported on every platform.</p>
+<p>If using libc++ and/or libc++abi, you may need to configure them to use
+compiler-rt rather than libgcc_s by passing <code class="docutils literal notranslate"><span class="pre">-DLIBCXX_USE_COMPILER_RT=YES</span></code>
+and/or <code class="docutils literal notranslate"><span class="pre">-DLIBCXXABI_USE_COMPILER_RT=YES</span></code> to <code class="docutils literal notranslate"><span class="pre">cmake</span></code>. Otherwise, you
+may end up with both runtime libraries linked into your program (this is
+typically harmless, but wasteful).</p>
+</div>
+<div class="section" id="libgcc-s-gnu">
+<h4>libgcc_s (GNU)<a class="headerlink" href="#libgcc-s-gnu" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html">GCCâs runtime library</a>
+can be used in place of compiler-rt. However, it lacks several functions
+that LLVM may emit references to, particularly when using Clangâs
+<code class="docutils literal notranslate"><span class="pre">__builtin_*_overflow</span></code> family of intrinsics.</p>
+<p>You can instruct Clang to use libgcc_s with the <code class="docutils literal notranslate"><span class="pre">--rtlib=libgcc</span></code> flag.
+This is not supported on every platform.</p>
+</div>
+</div>
+<div class="section" id="atomics-library">
+<h3><a class="toc-backref" href="#id16">Atomics library</a><a class="headerlink" href="#atomics-library" title="Permalink to this headline">¶</a></h3>
+<p>If your program makes use of atomic operations and the compiler is not able
+to lower them all directly to machine instructions (because there either is
+no known suitable machine instruction or the operand is not known to be
+suitably aligned), a call to a runtime library <code class="docutils literal notranslate"><span class="pre">__atomic_*</span></code> function
+will be generated. A runtime library containing these atomics functions is
+necessary for such programs.</p>
+<div class="section" id="id1">
+<h4>compiler-rt (LLVM)<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<p>compiler-rt contains an implementation of an atomics library.</p>
+</div>
+<div class="section" id="libatomic-gnu">
+<h4>libatomic (GNU)<a class="headerlink" href="#libatomic-gnu" title="Permalink to this headline">¶</a></h4>
+<p>libgcc_s does not provide an implementation of an atomics library. Instead,
+<a class="reference external" href="https://gcc.gnu.org/wiki/Atomic/GCCMM">GCCâs libatomic library</a> can be
+used to supply these when using libgcc_s.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang does not currently automatically link against libatomic when using
+libgcc_s. You may need to manually add <code class="docutils literal notranslate"><span class="pre">-latomic</span></code> to support this
+configuration when using non-native atomic operations (if you see link errors
+referring to <code class="docutils literal notranslate"><span class="pre">__atomic_*</span></code> functions).</p>
+</div>
+</div>
+</div>
+<div class="section" id="unwind-library">
+<h3><a class="toc-backref" href="#id17">Unwind library</a><a class="headerlink" href="#unwind-library" title="Permalink to this headline">¶</a></h3>
+<p>The unwind library provides a family of <code class="docutils literal notranslate"><span class="pre">_Unwind_*</span></code> functions implementing
+the language-neutral stack unwinding portion of the Itanium C++ ABI
+(<a class="reference external" href="https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#base-abi">Level I</a>).
+It is a dependency of the C++ ABI library, and sometimes is a dependency
+of other runtimes.</p>
+<div class="section" id="libunwind-llvm">
+<h4>libunwind (LLVM)<a class="headerlink" href="#libunwind-llvm" title="Permalink to this headline">¶</a></h4>
+<p>LLVMâs unwinder library is part of the llvm-project git repository. To
+build it, pass <code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_PROJECTS=libunwind</span></code> to the cmake invocation.</p>
+<p>If using libc++abi, you may need to configure it to use libunwind
+rather than libgcc_s by passing <code class="docutils literal notranslate"><span class="pre">-DLIBCXXABI_USE_LLVM_UNWINDER=YES</span></code>
+to <code class="docutils literal notranslate"><span class="pre">cmake</span></code>. If libc++abi is configured to use some version of
+libunwind, that library will be implicitly linked into binaries that
+link to libc++abi.</p>
+</div>
+<div class="section" id="id2">
+<h4>libgcc_s (GNU)<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<p>libgcc_s has an integrated unwinder, and does not need an external unwind
+library to be provided.</p>
+</div>
+<div class="section" id="libunwind-nongnu-org">
+<h4>libunwind (nongnu.org)<a class="headerlink" href="#libunwind-nongnu-org" title="Permalink to this headline">¶</a></h4>
+<p>This is another implementation of the libunwind specification.
+See <a class="reference external" href="https://www.nongnu.org/libunwind">libunwind (nongnu.org)</a>.</p>
+</div>
+<div class="section" id="libunwind-pathscale">
+<h4>libunwind (PathScale)<a class="headerlink" href="#libunwind-pathscale" title="Permalink to this headline">¶</a></h4>
+<p>This is another implementation of the libunwind specification.
+See <a class="reference external" href="https://github.com/pathscale/libunwind">libunwind (pathscale)</a>.</p>
+</div>
+</div>
+<div class="section" id="sanitizer-runtime">
+<h3><a class="toc-backref" href="#id18">Sanitizer runtime</a><a class="headerlink" href="#sanitizer-runtime" title="Permalink to this headline">¶</a></h3>
+<p>The instrumentation added by Clangâs sanitizers (<code class="docutils literal notranslate"><span class="pre">-fsanitize=...</span></code>) implicitly
+makes calls to a runtime library, in order to maintain side state about the
+execution of the program and to issue diagnostic messages when a problem is
+detected.</p>
+<p>The only supported implementation of these runtimes is provided by LLVMâs
+compiler-rt, and the relevant portion of that library
+(<code class="docutils literal notranslate"><span class="pre">libclang_rt.<sanitizer>.<arch>.a</span></code>)
+will be implicitly linked when linking with a <code class="docutils literal notranslate"><span class="pre">-fsanitize=...</span></code> flag.</p>
+</div>
+<div class="section" id="c-standard-library">
+<h3><a class="toc-backref" href="#id19">C standard library</a><a class="headerlink" href="#c-standard-library" title="Permalink to this headline">¶</a></h3>
+<p>Clang supports a wide variety of
+<a class="reference external" href="https://en.cppreference.com/w/c">C standard library</a>
+implementations.</p>
+</div>
+<div class="section" id="c-abi-library">
+<h3><a class="toc-backref" href="#id20">C++ ABI library</a><a class="headerlink" href="#c-abi-library" title="Permalink to this headline">¶</a></h3>
+<p>The C++ ABI library provides an implementation of the library portion of
+the Itanium C++ ABI, covering both the
+<a class="reference external" href="https://itanium-cxx-abi.github.io/cxx-abi/abi.html">support functionality in the main Itanium C++ ABI document</a> and
+<a class="reference external" href="https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#cxx-abi">Level II of the exception handling support</a>.
+References to the functions and objects in this library are implicitly
+generated by Clang when compiling C++ code.</p>
+<p>While it is possible to link C++ code using libstdc++ and code using libc++
+together into the same program (so long as you do not attempt to pass C++
+standard library objects across the boundary), it is not generally possible
+to have more than one C++ ABI library in a program.</p>
+<p>The version of the C++ ABI library used by Clang will be the one that the
+chosen C++ standard library was linked against. Several implementations are
+available:</p>
+<div class="section" id="libc-abi-llvm">
+<h4>libc++abi (LLVM)<a class="headerlink" href="#libc-abi-llvm" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="https://libcxxabi.llvm.org/">libc++abi</a> is LLVMâs implementation of this
+specification.</p>
+</div>
+<div class="section" id="libsupc-gnu">
+<h4>libsupc++ (GNU)<a class="headerlink" href="#libsupc-gnu" title="Permalink to this headline">¶</a></h4>
+<p>libsupc++ is GCCâs implementation of this specification. However, this
+library is only used when libstdc++ is linked statically. The dynamic
+library version of libstdc++ contains a copy of libsupc++.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Clang does not currently automatically link against libatomic when statically
+linking libstdc++. You may need to manually add <code class="docutils literal notranslate"><span class="pre">-lsupc++</span></code> to support this
+configuration when using <code class="docutils literal notranslate"><span class="pre">-static</span></code> or <code class="docutils literal notranslate"><span class="pre">-static-libstdc++</span></code>.</p>
+</div>
+</div>
+<div class="section" id="libcxxrt-pathscale">
+<h4>libcxxrt (PathScale)<a class="headerlink" href="#libcxxrt-pathscale" title="Permalink to this headline">¶</a></h4>
+<p>This is another implementation of the Itanium C++ ABI specification.
+See <a class="reference external" href="https://github.com/pathscale/libcxxrt">libcxxrt</a>.</p>
+</div>
+</div>
+<div class="section" id="id6">
+<h3><a class="toc-backref" href="#id21">C++ standard library</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
+<p>Clang supports use of either LLVMâs libc++ or GCCâs libstdc++ implementation
+of the <a class="reference external" href="https://en.cppreference.com/w/cpp">C++ standard library</a>.</p>
+<div class="section" id="libc-llvm">
+<h4>libc++ (LLVM)<a class="headerlink" href="#libc-llvm" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="https://libcxx.llvm.org/">libc++</a> is LLVMâs implementation of the C++
+standard library, aimed at being a complete implementation of the C++
+standards from C++11 onwards.</p>
+<p>You can instruct Clang to use libc++ with the <code class="docutils literal notranslate"><span class="pre">-stdlib=libc++</span></code> flag.</p>
+</div>
+<div class="section" id="libstdc-gnu">
+<h4>libstdc++ (GNU)<a class="headerlink" href="#libstdc-gnu" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference external" href="https://gcc.gnu.org/onlinedocs/libstdc++/">libstdc++</a> is GCCâs implementation
+of the C++ standard library. Clang supports a wide range of versions of
+libstdc++, from around version 4.2 onwards, and will implicitly work around
+some bugs in older versions of libstdc++.</p>
+<p>You can instruct Clang to use libstdc++ with the <code class="docutils literal notranslate"><span class="pre">-stdlib=libstdc++</span></code> flag.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="UsersManual.html">Clang Compiler Userâs Manual</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="LanguageExtensions.html">Clang Language Extensions</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/Tooling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/Tooling.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/Tooling.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/Tooling.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,152 @@
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Choosing the Right Interface for Your Application — Clang 9 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="External Clang Examples" href="ExternalClangExamples.html" />
+ <link rel="prev" title="Frequently Asked Questions (FAQ)" href="FAQ.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>Choosing the Right Interface for Your Application</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="FAQ.html">Frequently Asked Questions (FAQ)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ExternalClangExamples.html">External Clang Examples</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="choosing-the-right-interface-for-your-application">
+<h1>Choosing the Right Interface for Your Application<a class="headerlink" href="#choosing-the-right-interface-for-your-application" title="Permalink to this headline">¶</a></h1>
+<p>Clang provides infrastructure to write tools that need syntactic and semantic
+information about a program. This document will give a short introduction of
+the different ways to write clang tools, and their pros and cons.</p>
+<div class="section" id="libclang">
+<h2>LibClang<a class="headerlink" href="#libclang" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="https://clang.llvm.org/doxygen/group__CINDEX.html">LibClang</a> is a stable high
+level C interface to clang. When in doubt LibClang is probably the interface
+you want to use. Consider the other interfaces only when you have a good
+reason not to use LibClang.</p>
+<p>Canonical examples of when to use LibClang:</p>
+<ul class="simple">
+<li>Xcode</li>
+<li>Clang Python Bindings</li>
+</ul>
+<p>Use LibClang when youâ¦:</p>
+<ul class="simple">
+<li>want to interface with clang from other languages than C++</li>
+<li>need a stable interface that takes care to be backwards compatible</li>
+<li>want powerful high-level abstractions, like iterating through an AST with a
+cursor, and donât want to learn all the nitty gritty details of Clangâs AST.</li>
+</ul>
+<p>Do not use LibClang when youâ¦:</p>
+<ul class="simple">
+<li>want full control over the Clang AST</li>
+</ul>
+</div>
+<div class="section" id="clang-plugins">
+<h2>Clang Plugins<a class="headerlink" href="#clang-plugins" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="ClangPlugins.html"><span class="doc">Clang Plugins</span></a> allow you to run additional actions on the
+AST as part of a compilation. Plugins are dynamic libraries that are loaded at
+runtime by the compiler, and theyâre easy to integrate into your build
+environment.</p>
+<p>Canonical examples of when to use Clang Plugins:</p>
+<ul class="simple">
+<li>special lint-style warnings or errors for your project</li>
+<li>creating additional build artifacts from a single compile step</li>
+</ul>
+<p>Use Clang Plugins when youâ¦:</p>
+<ul class="simple">
+<li>need your tool to rerun if any of the dependencies change</li>
+<li>want your tool to make or break a build</li>
+<li>need full control over the Clang AST</li>
+</ul>
+<p>Do not use Clang Plugins when youâ¦:</p>
+<ul class="simple">
+<li>want to run tools outside of your build environment</li>
+<li>want full control on how Clang is set up, including mapping of in-memory
+virtual files</li>
+<li>need to run over a specific subset of files in your project which is not
+necessarily related to any changes which would trigger rebuilds</li>
+</ul>
+</div>
+<div class="section" id="libtooling">
+<h2>LibTooling<a class="headerlink" href="#libtooling" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="LibTooling.html"><span class="doc">LibTooling</span></a> is a C++ interface aimed at writing standalone
+tools, as well as integrating into services that run clang tools. Canonical
+examples of when to use LibTooling:</p>
+<ul class="simple">
+<li>a simple syntax checker</li>
+<li>refactoring tools</li>
+</ul>
+<p>Use LibTooling when youâ¦:</p>
+<ul class="simple">
+<li>want to run tools over a single file, or a specific subset of files,
+independently of the build system</li>
+<li>want full control over the Clang AST</li>
+<li>want to share code with Clang Plugins</li>
+</ul>
+<p>Do not use LibTooling when youâ¦:</p>
+<ul class="simple">
+<li>want to run as part of the build triggered by dependency changes</li>
+<li>want a stable interface so you donât need to change your code when the AST API
+changes</li>
+<li>want high level abstractions like cursors and code completion out of the box</li>
+<li>do not want to write your tools in C++</li>
+</ul>
+<p><a class="reference internal" href="ClangTools.html"><span class="doc">Clang tools</span></a> are a collection of specific developer tools
+built on top of the LibTooling infrastructure as part of the Clang project.
+They are targeted at automating and improving core development activities of
+C/C++ developers.</p>
+<p>Examples of tools we are building or planning as part of the Clang project:</p>
+<ul class="simple">
+<li>Syntax checking (<strong class="program">clang-check</strong>)</li>
+<li>Automatic fixing of compile errors (<strong class="program">clang-fixit</strong>)</li>
+<li>Automatic code formatting (<strong class="program">clang-format</strong>)</li>
+<li>Migration tools for new features in new language standards</li>
+<li>Core refactoring tools</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="FAQ.html">Frequently Asked Questions (FAQ)</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="ExternalClangExamples.html">External Clang Examples</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/UndefinedBehaviorSanitizer.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,411 @@
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>UndefinedBehaviorSanitizer — Clang 9 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="DataFlowSanitizer" href="DataFlowSanitizer.html" />
+ <link rel="prev" title="MemorySanitizer" href="MemorySanitizer.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>UndefinedBehaviorSanitizer</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="MemorySanitizer.html">MemorySanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="DataFlowSanitizer.html">DataFlowSanitizer</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="undefinedbehaviorsanitizer">
+<h1>UndefinedBehaviorSanitizer<a class="headerlink" href="#undefinedbehaviorsanitizer" 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="id1">Introduction</a></li>
+<li><a class="reference internal" href="#how-to-build" id="id2">How to build</a></li>
+<li><a class="reference internal" href="#usage" id="id3">Usage</a></li>
+<li><a class="reference internal" href="#available-checks" id="id4">Available checks</a><ul>
+<li><a class="reference internal" href="#volatile" id="id5">Volatile</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#minimal-runtime" id="id6">Minimal Runtime</a></li>
+<li><a class="reference internal" href="#stack-traces-and-report-symbolization" id="id7">Stack traces and report symbolization</a></li>
+<li><a class="reference internal" href="#silencing-unsigned-integer-overflow" id="id8">Silencing Unsigned Integer Overflow</a></li>
+<li><a class="reference internal" href="#issue-suppression" id="id9">Issue Suppression</a><ul>
+<li><a class="reference internal" href="#disabling-instrumentation-with-attribute-no-sanitize-undefined" id="id10">Disabling Instrumentation with <code class="docutils literal notranslate"><span class="pre">__attribute__((no_sanitize("undefined")))</span></code></a></li>
+<li><a class="reference internal" href="#suppressing-errors-in-recompiled-code-blacklist" id="id11">Suppressing Errors in Recompiled Code (Blacklist)</a></li>
+<li><a class="reference internal" href="#runtime-suppressions" id="id12">Runtime suppressions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#supported-platforms" id="id13">Supported Platforms</a></li>
+<li><a class="reference internal" href="#current-status" id="id14">Current Status</a></li>
+<li><a class="reference internal" href="#additional-configuration" id="id15">Additional Configuration</a><ul>
+<li><a class="reference internal" href="#example" id="id16">Example</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#more-information" id="id17">More Information</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>UndefinedBehaviorSanitizer (UBSan) is a fast undefined behavior detector.
+UBSan modifies the program at compile-time to catch various kinds of undefined
+behavior during program execution, for example:</p>
+<ul class="simple">
+<li>Using misaligned or null pointer</li>
+<li>Signed integer overflow</li>
+<li>Conversion to, from, or between floating-point types which would
+overflow the destination</li>
+</ul>
+<p>See the full list of available <a class="reference internal" href="#ubsan-checks"><span class="std std-ref">checks</span></a> below.</p>
+<p>UBSan has an optional run-time library which provides better error reporting.
+The checks have small runtime cost and no impact on address space layout or ABI.</p>
+</div>
+<div class="section" id="how-to-build">
+<h2><a class="toc-backref" href="#id2">How to build</a><a class="headerlink" href="#how-to-build" title="Permalink to this headline">¶</a></h2>
+<p>Build LLVM/Clang with <a class="reference external" href="https://llvm.org/docs/CMake.html">CMake</a>.</p>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>Use <code class="docutils literal notranslate"><span class="pre">clang++</span></code> to compile and link your program with <code class="docutils literal notranslate"><span class="pre">-fsanitize=undefined</span></code>
+flag. Make sure to use <code class="docutils literal notranslate"><span class="pre">clang++</span></code> (not <code class="docutils literal notranslate"><span class="pre">ld</span></code>) as a linker, so that your
+executable is linked with proper UBSan runtime libraries. You can use <code class="docutils literal notranslate"><span class="pre">clang</span></code>
+instead of <code class="docutils literal notranslate"><span class="pre">clang++</span></code> if youâre compiling/linking C code.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> cat test.cc
+<span class="go">int main(int argc, char **argv) {</span>
+<span class="go"> int k = 0x7fffffff;</span>
+<span class="go"> k += argc;</span>
+<span class="go"> return 0;</span>
+<span class="go">}</span>
+<span class="gp">%</span> clang++ -fsanitize<span class="o">=</span>undefined test.cc
+<span class="gp">%</span> ./a.out
+<span class="go">test.cc:3:5: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int'</span>
+</pre></div>
+</div>
+<p>You can enable only a subset of <a class="reference internal" href="#ubsan-checks"><span class="std std-ref">checks</span></a> offered by UBSan,
+and define the desired behavior for each kind of check:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=...</span></code>: print a verbose error report and continue execution (default);</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fno-sanitize-recover=...</span></code>: print a verbose error report and exit the program;</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize-trap=...</span></code>: execute a trap instruction (doesnât require UBSan run-time support).</li>
+</ul>
+<p>For example if you compile/link your program as:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> clang++ -fsanitize<span class="o">=</span>signed-integer-overflow,null,alignment -fno-sanitize-recover<span class="o">=</span>null -fsanitize-trap<span class="o">=</span>alignment
+</pre></div>
+</div>
+<p>the program will continue execution after signed integer overflows, exit after
+the first invalid use of a null pointer, and trap after the first use of misaligned
+pointer.</p>
+</div>
+<div class="section" id="available-checks">
+<span id="ubsan-checks"></span><h2><a class="toc-backref" href="#id4">Available checks</a><a class="headerlink" href="#available-checks" title="Permalink to this headline">¶</a></h2>
+<p>Available checks are:</p>
+<blockquote>
+<div><ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=alignment</span></code>: Use of a misaligned pointer or creation
+of a misaligned reference. Also sanitizes assume_aligned-like attributes.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=bool</span></code>: Load of a <code class="docutils literal notranslate"><span class="pre">bool</span></code> value which is neither
+<code class="docutils literal notranslate"><span class="pre">true</span></code> nor <code class="docutils literal notranslate"><span class="pre">false</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=builtin</span></code>: Passing invalid values to compiler builtins.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=bounds</span></code>: Out of bounds array indexing, in cases
+where the array bound can be statically determined.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=enum</span></code>: Load of a value of an enumerated type which
+is not in the range of representable values for that enumerated
+type.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=float-cast-overflow</span></code>: Conversion to, from, or
+between floating-point types which would overflow the
+destination. Because the range of representable values for all
+floating-point types supported by Clang is [-inf, +inf], the only
+cases detected are conversions from floating point to integer types.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=float-divide-by-zero</span></code>: Floating point division by
+zero. This is undefined per the C and C++ standards, but is defined
+by Clang (and by ISO/IEC/IEEE 60559 / IEEE 754) as producing either an
+infinity or NaN value, so is not included in <code class="docutils literal notranslate"><span class="pre">-fsanitize=undefined</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=function</span></code>: Indirect call of a function through a
+function pointer of the wrong type (Darwin/Linux, C++ and x86/x86_64
+only).</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-unsigned-integer-truncation</span></code>,
+<code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-signed-integer-truncation</span></code>: Implicit conversion from
+integer of larger bit width to smaller bit width, if that results in data
+loss. That is, if the demoted value, after casting back to the original
+width, is not equal to the original value before the downcast.
+The <code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-unsigned-integer-truncation</span></code> handles conversions
+between two <code class="docutils literal notranslate"><span class="pre">unsigned</span></code> types, while
+<code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-signed-integer-truncation</span></code> handles the rest of the
+conversions - when either one, or both of the types are signed.
+Issues caught by these sanitizers are not undefined behavior,
+but are often unintentional.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-integer-sign-change</span></code>: Implicit conversion between
+integer types, if that changes the sign of the value. That is, if the the
+original value was negative and the new value is positive (or zero),
+or the original value was positive, and the new value is negative.
+Issues caught by this sanitizer are not undefined behavior,
+but are often unintentional.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=integer-divide-by-zero</span></code>: Integer division by zero.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=nonnull-attribute</span></code>: Passing null pointer as a function
+parameter which is declared to never be null.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=null</span></code>: Use of a null pointer or creation of a null
+reference.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=nullability-arg</span></code>: Passing null as a function parameter
+which is annotated with <code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=nullability-assign</span></code>: Assigning null to an lvalue which
+is annotated with <code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=nullability-return</span></code>: Returning null from a function with
+a return type annotated with <code class="docutils literal notranslate"><span class="pre">_Nonnull</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=object-size</span></code>: An attempt to potentially use bytes which
+the optimizer can determine are not part of the object being accessed.
+This will also detect some types of undefined behavior that may not
+directly access memory, but are provably incorrect given the size of
+the objects involved, such as invalid downcasts and calling methods on
+invalid pointers. These checks are made in terms of
+<code class="docutils literal notranslate"><span class="pre">__builtin_object_size</span></code>, and consequently may be able to detect more
+problems at higher optimization levels.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=pointer-overflow</span></code>: Performing pointer arithmetic which
+overflows.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=return</span></code>: In C++, reaching the end of a
+value-returning function without returning a value.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=returns-nonnull-attribute</span></code>: Returning null pointer
+from a function which is declared to never return null.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=shift</span></code>: Shift operators where the amount shifted is
+greater or equal to the promoted bit-width of the left hand side
+or less than zero, or where the left hand side is negative. For a
+signed left shift, also checks for signed overflow in C, and for
+unsigned overflow in C++. You can use <code class="docutils literal notranslate"><span class="pre">-fsanitize=shift-base</span></code> or
+<code class="docutils literal notranslate"><span class="pre">-fsanitize=shift-exponent</span></code> to check only left-hand side or
+right-hand side of shift operation, respectively.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=signed-integer-overflow</span></code>: Signed integer overflow, where the
+result of a signed integer computation cannot be represented in its type.
+This includes all the checks covered by <code class="docutils literal notranslate"><span class="pre">-ftrapv</span></code>, as well as checks for
+signed division overflow (<code class="docutils literal notranslate"><span class="pre">INT_MIN/-1</span></code>), but not checks for
+lossy implicit conversions performed before the computation
+(see <code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-conversion</span></code>). Both of these two issues are
+handled by <code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-conversion</span></code> group of checks.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=unreachable</span></code>: If control flow reaches an unreachable
+program point.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=unsigned-integer-overflow</span></code>: Unsigned integer overflow, where
+the result of an unsigned integer computation cannot be represented in its
+type. Unlike signed integer overflow, this is not undefined behavior, but
+it is often unintentional. This sanitizer does not check for lossy implicit
+conversions performed before such a computation
+(see <code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-conversion</span></code>).</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=vla-bound</span></code>: A variable-length array whose bound
+does not evaluate to a positive value.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=vptr</span></code>: Use of an object whose vptr indicates that it is of
+the wrong dynamic type, or that its lifetime has not begun or has ended.
+Incompatible with <code class="docutils literal notranslate"><span class="pre">-fno-rtti</span></code>. Link must be performed by <code class="docutils literal notranslate"><span class="pre">clang++</span></code>, not
+<code class="docutils literal notranslate"><span class="pre">clang</span></code>, to make sure C++-specific parts of the runtime library and C++
+standard libraries are present.</li>
+</ul>
+</div></blockquote>
+<dl class="docutils">
+<dt>You can also use the following check groups:</dt>
+<dd><ul class="first last simple">
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=undefined</span></code>: All of the checks listed above other than
+<code class="docutils literal notranslate"><span class="pre">float-divide-by-zero</span></code>, <code class="docutils literal notranslate"><span class="pre">unsigned-integer-overflow</span></code>,
+<code class="docutils literal notranslate"><span class="pre">implicit-conversion</span></code>, and the <code class="docutils literal notranslate"><span class="pre">nullability-*</span></code> group of checks.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=undefined-trap</span></code>: Deprecated alias of
+<code class="docutils literal notranslate"><span class="pre">-fsanitize=undefined</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-integer-truncation</span></code>: Catches lossy integral
+conversions. Enables <code class="docutils literal notranslate"><span class="pre">implicit-signed-integer-truncation</span></code> and
+<code class="docutils literal notranslate"><span class="pre">implicit-unsigned-integer-truncation</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-integer-arithmetic-value-change</span></code>: Catches implicit
+conversions that change the arithmetic value of the integer. Enables
+<code class="docutils literal notranslate"><span class="pre">implicit-signed-integer-truncation</span></code> and <code class="docutils literal notranslate"><span class="pre">implicit-integer-sign-change</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=implicit-conversion</span></code>: Checks for suspicious
+behavior of implicit conversions. Enables
+<code class="docutils literal notranslate"><span class="pre">implicit-unsigned-integer-truncation</span></code>,
+<code class="docutils literal notranslate"><span class="pre">implicit-signed-integer-truncation</span></code>, and
+<code class="docutils literal notranslate"><span class="pre">implicit-integer-sign-change</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=integer</span></code>: Checks for undefined or suspicious integer
+behavior (e.g. unsigned integer overflow).
+Enables <code class="docutils literal notranslate"><span class="pre">signed-integer-overflow</span></code>, <code class="docutils literal notranslate"><span class="pre">unsigned-integer-overflow</span></code>,
+<code class="docutils literal notranslate"><span class="pre">shift</span></code>, <code class="docutils literal notranslate"><span class="pre">integer-divide-by-zero</span></code>,
+<code class="docutils literal notranslate"><span class="pre">implicit-unsigned-integer-truncation</span></code>,
+<code class="docutils literal notranslate"><span class="pre">implicit-signed-integer-truncation</span></code>, and
+<code class="docutils literal notranslate"><span class="pre">implicit-integer-sign-change</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=nullability</span></code>: Enables <code class="docutils literal notranslate"><span class="pre">nullability-arg</span></code>,
+<code class="docutils literal notranslate"><span class="pre">nullability-assign</span></code>, and <code class="docutils literal notranslate"><span class="pre">nullability-return</span></code>. While violating
+nullability does not have undefined behavior, it is often unintentional,
+so UBSan offers to catch it.</li>
+</ul>
+</dd>
+</dl>
+<div class="section" id="volatile">
+<h3><a class="toc-backref" href="#id5">Volatile</a><a class="headerlink" href="#volatile" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">null</span></code>, <code class="docutils literal notranslate"><span class="pre">alignment</span></code>, <code class="docutils literal notranslate"><span class="pre">object-size</span></code>, and <code class="docutils literal notranslate"><span class="pre">vptr</span></code> checks do not apply
+to pointers to types with the <code class="docutils literal notranslate"><span class="pre">volatile</span></code> qualifier.</p>
+</div>
+</div>
+<div class="section" id="minimal-runtime">
+<h2><a class="toc-backref" href="#id6">Minimal Runtime</a><a class="headerlink" href="#minimal-runtime" title="Permalink to this headline">¶</a></h2>
+<p>There is a minimal UBSan runtime available suitable for use in production
+environments. This runtime has a small attack surface. It only provides very
+basic issue logging and deduplication, and does not support
+<code class="docutils literal notranslate"><span class="pre">-fsanitize=function</span></code> and <code class="docutils literal notranslate"><span class="pre">-fsanitize=vptr</span></code> checking.</p>
+<p>To use the minimal runtime, add <code class="docutils literal notranslate"><span class="pre">-fsanitize-minimal-runtime</span></code> to the clang
+command line options. For example, if youâre used to compiling with
+<code class="docutils literal notranslate"><span class="pre">-fsanitize=undefined</span></code>, you could enable the minimal runtime with
+<code class="docutils literal notranslate"><span class="pre">-fsanitize=undefined</span> <span class="pre">-fsanitize-minimal-runtime</span></code>.</p>
+</div>
+<div class="section" id="stack-traces-and-report-symbolization">
+<h2><a class="toc-backref" href="#id7">Stack traces and report symbolization</a><a class="headerlink" href="#stack-traces-and-report-symbolization" title="Permalink to this headline">¶</a></h2>
+<p>If you want UBSan to print symbolized stack trace for each error report, you
+will need to:</p>
+<ol class="arabic simple">
+<li>Compile with <code class="docutils literal notranslate"><span class="pre">-g</span></code> and <code class="docutils literal notranslate"><span class="pre">-fno-omit-frame-pointer</span></code> to get proper debug
+information in your binary.</li>
+<li>Run your program with environment variable
+<code class="docutils literal notranslate"><span class="pre">UBSAN_OPTIONS=print_stacktrace=1</span></code>.</li>
+<li>Make sure <code class="docutils literal notranslate"><span class="pre">llvm-symbolizer</span></code> binary is in <code class="docutils literal notranslate"><span class="pre">PATH</span></code>.</li>
+</ol>
+</div>
+<div class="section" id="silencing-unsigned-integer-overflow">
+<h2><a class="toc-backref" href="#id8">Silencing Unsigned Integer Overflow</a><a class="headerlink" href="#silencing-unsigned-integer-overflow" title="Permalink to this headline">¶</a></h2>
+<p>To silence reports from unsigned integer overflow, you can set
+<code class="docutils literal notranslate"><span class="pre">UBSAN_OPTIONS=silence_unsigned_overflow=1</span></code>. This feature, combined with
+<code class="docutils literal notranslate"><span class="pre">-fsanitize-recover=unsigned-integer-overflow</span></code>, is particularly useful for
+providing fuzzing signal without blowing up logs.</p>
+</div>
+<div class="section" id="issue-suppression">
+<h2><a class="toc-backref" href="#id9">Issue Suppression</a><a class="headerlink" href="#issue-suppression" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer is not expected to produce false positives.
+If you see one, look again; most likely it is a true positive!</p>
+<div class="section" id="disabling-instrumentation-with-attribute-no-sanitize-undefined">
+<h3><a class="toc-backref" href="#id10">Disabling Instrumentation with <code class="docutils literal notranslate"><span class="pre">__attribute__((no_sanitize("undefined")))</span></code></a><a class="headerlink" href="#disabling-instrumentation-with-attribute-no-sanitize-undefined" title="Permalink to this headline">¶</a></h3>
+<p>You disable UBSan checks for particular functions with
+<code class="docutils literal notranslate"><span class="pre">__attribute__((no_sanitize("undefined")))</span></code>. You can use all values of
+<code class="docutils literal notranslate"><span class="pre">-fsanitize=</span></code> flag in this attribute, e.g. if your function deliberately
+contains possible signed integer overflow, you can use
+<code class="docutils literal notranslate"><span class="pre">__attribute__((no_sanitize("signed-integer-overflow")))</span></code>.</p>
+<p>This attribute may not be
+supported by other compilers, so consider using it together with
+<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">defined(__clang__)</span></code>.</p>
+</div>
+<div class="section" id="suppressing-errors-in-recompiled-code-blacklist">
+<h3><a class="toc-backref" href="#id11">Suppressing Errors in Recompiled Code (Blacklist)</a><a class="headerlink" href="#suppressing-errors-in-recompiled-code-blacklist" title="Permalink to this headline">¶</a></h3>
+<p>UndefinedBehaviorSanitizer supports <code class="docutils literal notranslate"><span class="pre">src</span></code> and <code class="docutils literal notranslate"><span class="pre">fun</span></code> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><span class="doc">Sanitizer special case list</span></a>, that can be used to suppress error reports
+in the specified source files or functions.</p>
+</div>
+<div class="section" id="runtime-suppressions">
+<h3><a class="toc-backref" href="#id12">Runtime suppressions</a><a class="headerlink" href="#runtime-suppressions" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes you can suppress UBSan error reports for specific files, functions,
+or libraries without recompiling the code. You need to pass a path to
+suppression file in a <code class="docutils literal notranslate"><span class="pre">UBSAN_OPTIONS</span></code> environment variable.</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">UBSAN_OPTIONS</span><span class="o">=</span><span class="nv">suppressions</span><span class="o">=</span>MyUBSan.supp
+</pre></div>
+</div>
+<p>You need to specify a <a class="reference internal" href="#ubsan-checks"><span class="std std-ref">check</span></a> you are suppressing and the
+bug location. For example:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>signed-integer-overflow:file-with-known-overflow.cpp
+alignment:function_doing_unaligned_access
+vptr:shared_object_with_vptr_failures.so
+</pre></div>
+</div>
+<p>There are several limitations:</p>
+<ul class="simple">
+<li>Sometimes your binary must have enough debug info and/or symbol table, so
+that the runtime could figure out source file or function name to match
+against the suppression.</li>
+<li>It is only possible to suppress recoverable checks. For the example above,
+you can additionally pass
+<code class="docutils literal notranslate"><span class="pre">-fsanitize-recover=signed-integer-overflow,alignment,vptr</span></code>, although
+most of UBSan checks are recoverable by default.</li>
+<li>Check groups (like <code class="docutils literal notranslate"><span class="pre">undefined</span></code>) canât be used in suppressions file, only
+fine-grained checks are supported.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="supported-platforms">
+<h2><a class="toc-backref" href="#id13">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer is supported on the following operating systems:</p>
+<ul class="simple">
+<li>Android</li>
+<li>Linux</li>
+<li>NetBSD</li>
+<li>FreeBSD</li>
+<li>OpenBSD</li>
+<li>macOS</li>
+<li>Windows</li>
+</ul>
+<p>The runtime library is relatively portable and platform independent. If the OS
+you need is not listed above, UndefinedBehaviorSanitizer may already work for
+it, or could be made to work with a minor porting effort.</p>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id14">Current Status</a><a class="headerlink" href="#current-status" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer is available on selected platforms starting from LLVM
+3.3. The test suite is integrated into the CMake build and can be run with
+<code class="docutils literal notranslate"><span class="pre">check-ubsan</span></code> command.</p>
+</div>
+<div class="section" id="additional-configuration">
+<h2><a class="toc-backref" href="#id15">Additional Configuration</a><a class="headerlink" href="#additional-configuration" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer adds static check data for each check unless it is
+in trap mode. This check data includes the full file name. The option
+<code class="docutils literal notranslate"><span class="pre">-fsanitize-undefined-strip-path-components=N</span></code> can be used to trim this
+information. If <code class="docutils literal notranslate"><span class="pre">N</span></code> is positive, file information emitted by
+UndefinedBehaviorSanitizer will drop the first <code class="docutils literal notranslate"><span class="pre">N</span></code> components from the file
+path. If <code class="docutils literal notranslate"><span class="pre">N</span></code> is negative, the last <code class="docutils literal notranslate"><span class="pre">N</span></code> components will be kept.</p>
+<div class="section" id="example">
+<h3><a class="toc-backref" href="#id16">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
+<p>For a file called <code class="docutils literal notranslate"><span class="pre">/code/library/file.cpp</span></code>, here is what would be emitted:</p>
+<ul class="simple">
+<li>Default (No flag, or <code class="docutils literal notranslate"><span class="pre">-fsanitize-undefined-strip-path-components=0</span></code>): <code class="docutils literal notranslate"><span class="pre">/code/library/file.cpp</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize-undefined-strip-path-components=1</span></code>: <code class="docutils literal notranslate"><span class="pre">code/library/file.cpp</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize-undefined-strip-path-components=2</span></code>: <code class="docutils literal notranslate"><span class="pre">library/file.cpp</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize-undefined-strip-path-components=-1</span></code>: <code class="docutils literal notranslate"><span class="pre">file.cpp</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize-undefined-strip-path-components=-2</span></code>: <code class="docutils literal notranslate"><span class="pre">library/file.cpp</span></code></li>
+</ul>
+</div>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id17">More Information</a><a class="headerlink" href="#more-information" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>From LLVM project blog:
+<a class="reference external" href="http://blog.llvm.org/2011/05/what-every-c-programmer-should-know.html">What Every C Programmer Should Know About Undefined Behavior</a></li>
+<li>From John Regehrâs <em>Embedded in Academia</em> blog:
+<a class="reference external" href="https://blog.regehr.org/archives/213">A Guide to Undefined Behavior in C and C++</a></li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="MemorySanitizer.html">MemorySanitizer</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="DataFlowSanitizer.html">DataFlowSanitizer</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/UsersManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/UsersManual.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/UsersManual.html (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/UsersManual.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,3338 @@
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Clang Compiler Userâs Manual — Clang 9 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Assembling a Complete Toolchain" href="Toolchain.html" />
+ <link rel="prev" title="Clang 9.0.0 Release Notes" href="ReleaseNotes.html" />
+ </head><body>
+ <div class="header" role="banner"><h1 class="heading"><a href="index.html">
+ <span>Clang 9 documentation</span></a></h1>
+ <h2 class="heading"><span>Clang Compiler Userâs Manual</span></h2>
+ </div>
+ <div class="topnav" role="navigation" aria-label="top navigation">
+
+ <p>
+ « <a href="ReleaseNotes.html">Clang 9.0.0 Release Notes</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Toolchain.html">Assembling a Complete Toolchain</a> »
+ </p>
+
+ </div>
+ <div class="content">
+
+
+ <div class="section" id="clang-compiler-user-s-manual">
+<h1>Clang Compiler Userâs Manual<a class="headerlink" href="#clang-compiler-user-s-manual" 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="id10">Introduction</a><ul>
+<li><a class="reference internal" href="#terminology" id="id11">Terminology</a></li>
+<li><a class="reference internal" href="#basic-usage" id="id12">Basic Usage</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#command-line-options" id="id13">Command Line Options</a><ul>
+<li><a class="reference internal" href="#options-to-control-error-and-warning-messages" id="id14">Options to Control Error and Warning Messages</a><ul>
+<li><a class="reference internal" href="#formatting-of-diagnostics" id="id15">Formatting of Diagnostics</a></li>
+<li><a class="reference internal" href="#individual-warning-groups" id="id16">Individual Warning Groups</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#options-to-control-clang-crash-diagnostics" id="id17">Options to Control Clang Crash Diagnostics</a></li>
+<li><a class="reference internal" href="#options-to-emit-optimization-reports" id="id18">Options to Emit Optimization Reports</a><ul>
+<li><a class="reference internal" href="#current-limitations" id="id19">Current limitations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#other-options" id="id20">Other Options</a></li>
+<li><a class="reference internal" href="#configuration-files" id="id21">Configuration files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#language-and-target-independent-features" id="id22">Language and Target-Independent Features</a><ul>
+<li><a class="reference internal" href="#controlling-errors-and-warnings" id="id23">Controlling Errors and Warnings</a><ul>
+<li><a class="reference internal" href="#controlling-how-clang-displays-diagnostics" id="id24">Controlling How Clang Displays Diagnostics</a></li>
+<li><a class="reference internal" href="#diagnostic-mappings" id="id25">Diagnostic Mappings</a></li>
+<li><a class="reference internal" href="#diagnostic-categories" id="id26">Diagnostic Categories</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-command-line-flags" id="id27">Controlling Diagnostics via Command Line Flags</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-pragmas" id="id28">Controlling Diagnostics via Pragmas</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-in-system-headers" id="id29">Controlling Diagnostics in System Headers</a></li>
+<li><a class="reference internal" href="#enabling-all-diagnostics" id="id30">Enabling All Diagnostics</a></li>
+<li><a class="reference internal" href="#controlling-static-analyzer-diagnostics" id="id31">Controlling Static Analyzer Diagnostics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#precompiled-headers" id="id32">Precompiled Headers</a><ul>
+<li><a class="reference internal" href="#generating-a-pch-file" id="id33">Generating a PCH File</a></li>
+<li><a class="reference internal" href="#using-a-pch-file" id="id34">Using a PCH File</a></li>
+<li><a class="reference internal" href="#relocatable-pch-files" id="id35">Relocatable PCH Files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-code-generation" id="id36">Controlling Code Generation</a></li>
+<li><a class="reference internal" href="#profile-guided-optimization" id="id37">Profile Guided Optimization</a><ul>
+<li><a class="reference internal" href="#differences-between-sampling-and-instrumentation" id="id38">Differences Between Sampling and Instrumentation</a></li>
+<li><a class="reference internal" href="#using-sampling-profilers" id="id39">Using Sampling Profilers</a><ul>
+<li><a class="reference internal" href="#sample-profile-formats" id="id40">Sample Profile Formats</a></li>
+<li><a class="reference internal" href="#sample-profile-text-format" id="id41">Sample Profile Text Format</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#profiling-with-instrumentation" id="id42">Profiling with Instrumentation</a></li>
+<li><a class="reference internal" href="#disabling-instrumentation" id="id43">Disabling Instrumentation</a></li>
+<li><a class="reference internal" href="#profile-remapping" id="id44">Profile remapping</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#gcov-based-profiling" id="id45">GCOV-based Profiling</a></li>
+<li><a class="reference internal" href="#controlling-debug-information" id="id46">Controlling Debug Information</a><ul>
+<li><a class="reference internal" href="#controlling-size-of-debug-information" id="id47">Controlling Size of Debug Information</a></li>
+<li><a class="reference internal" href="#controlling-macro-debug-info-generation" id="id48">Controlling Macro Debug Info Generation</a></li>
+<li><a class="reference internal" href="#controlling-debugger-tuning" id="id49">Controlling Debugger âTuningâ</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-llvm-ir-output" id="id50">Controlling LLVM IR Output</a><ul>
+<li><a class="reference internal" href="#controlling-value-names-in-llvm-ir" id="id51">Controlling Value Names in LLVM IR</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#comment-parsing-options" id="id52">Comment Parsing Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-language-features" id="id53">C Language Features</a><ul>
+<li><a class="reference internal" href="#extensions-supported-by-clang" id="id54">Extensions supported by clang</a></li>
+<li><a class="reference internal" href="#differences-between-various-standard-modes" id="id55">Differences between various standard modes</a></li>
+<li><a class="reference internal" href="#gcc-extensions-not-implemented-yet" id="id56">GCC extensions not implemented yet</a></li>
+<li><a class="reference internal" href="#intentionally-unsupported-gcc-extensions" id="id57">Intentionally unsupported GCC extensions</a></li>
+<li><a class="reference internal" href="#microsoft-extensions" id="id58">Microsoft extensions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#cxx" id="id59">C++ Language Features</a><ul>
+<li><a class="reference internal" href="#controlling-implementation-limits" id="id60">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#objective-c-language-features" id="id61">Objective-C Language Features</a></li>
+<li><a class="reference internal" href="#objcxx" id="id62">Objective-C++ Language Features</a></li>
+<li><a class="reference internal" href="#openmp-features" id="id63">OpenMP Features</a><ul>
+<li><a class="reference internal" href="#id6" id="id64">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-features" id="id65">OpenCL Features</a><ul>
+<li><a class="reference internal" href="#opencl-specific-options" id="id66">OpenCL Specific Options</a></li>
+<li><a class="reference internal" href="#opencl-targets" id="id67">OpenCL Targets</a><ul>
+<li><a class="reference internal" href="#specific-targets" id="id68">Specific Targets</a></li>
+<li><a class="reference internal" href="#generic-targets" id="id69">Generic Targets</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-header" id="id70">OpenCL Header</a></li>
+<li><a class="reference internal" href="#opencl-extensions" id="id71">OpenCL Extensions</a></li>
+<li><a class="reference internal" href="#opencl-metadata" id="id72">OpenCL Metadata</a></li>
+<li><a class="reference internal" href="#opencl-specific-attributes" id="id73">OpenCL-Specific Attributes</a><ul>
+<li><a class="reference internal" href="#nosvm" id="id74">nosvm</a></li>
+<li><a class="reference internal" href="#opencl-unroll-hint" id="id75">opencl_unroll_hint</a></li>
+<li><a class="reference internal" href="#convergent" id="id76">convergent</a></li>
+<li><a class="reference internal" href="#noduplicate" id="id77">noduplicate</a></li>
+<li><a class="reference internal" href="#address-space" id="id78">address_space</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#opencl-builtins" id="id79">OpenCL builtins</a></li>
+<li><a class="reference internal" href="#c-for-opencl" id="id80">C++ for OpenCL</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-specific-features-and-limitations" id="id81">Target-Specific Features and Limitations</a><ul>
+<li><a class="reference internal" href="#cpu-architectures-features-and-limitations" id="id82">CPU Architectures Features and Limitations</a><ul>
+<li><a class="reference internal" href="#x86" id="id83">X86</a></li>
+<li><a class="reference internal" href="#arm" id="id84">ARM</a></li>
+<li><a class="reference internal" href="#powerpc" id="id85">PowerPC</a></li>
+<li><a class="reference internal" href="#other-platforms" id="id86">Other platforms</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#operating-system-features-and-limitations" id="id87">Operating System Features and Limitations</a><ul>
+<li><a class="reference internal" href="#darwin-macos" id="id88">Darwin (macOS)</a></li>
+<li><a class="reference internal" href="#windows" id="id89">Windows</a><ul>
+<li><a class="reference internal" href="#cygwin" id="id90">Cygwin</a></li>
+<li><a class="reference internal" href="#mingw32" id="id91">MinGW32</a></li>
+<li><a class="reference internal" href="#mingw-w64" id="id92">MinGW-w64</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#clang-cl" id="id93">clang-cl</a><ul>
+<li><a class="reference internal" href="#id9" id="id94">Command-Line Options</a><ul>
+<li><a class="reference internal" href="#the-clang-option" id="id95">The /clang: Option</a></li>
+<li><a class="reference internal" href="#the-zc-dllexportinlines-option" id="id96">The /Zc:dllexportInlines- Option</a></li>
+<li><a class="reference internal" href="#the-fallback-option" id="id97">The /fallback Option</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id10">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>The Clang Compiler is an open-source compiler for the C family of
+programming languages, aiming to be the best in class implementation of
+these languages. Clang builds on the LLVM optimizer and code generator,
+allowing it to provide high-quality optimization and code generation
+support for many targets. For more general information, please see the
+<a class="reference external" href="https://clang.llvm.org">Clang Web Site</a> or the <a class="reference external" href="https://llvm.org">LLVM Web
+Site</a>.</p>
+<p>This document describes important notes about using Clang as a compiler
+for an end-user, documenting the supported features, command line
+options, etc. If you are interested in using Clang to build a tool that
+processes code, please see <a class="reference internal" href="InternalsManual.html"><span class="doc">âClangâ CFE Internals Manual</span></a>. If you are interested in the
+<a class="reference external" href="https://clang-analyzer.llvm.org">Clang Static Analyzer</a>, please see its web
+page.</p>
+<p>Clang is one component in a complete toolchain for C family languages.
+A separate document describes the other pieces necessary to
+<a class="reference internal" href="Toolchain.html"><span class="doc">assemble a complete toolchain</span></a>.</p>
+<p>Clang is designed to support the C family of programming languages,
+which includes <a class="reference internal" href="#c"><span class="std std-ref">C</span></a>, <a class="reference internal" href="#objc"><span class="std std-ref">Objective-C</span></a>, <a class="reference internal" href="#cxx"><span class="std std-ref">C++</span></a>, and
+<a class="reference internal" href="#objcxx"><span class="std std-ref">Objective-C++</span></a> as well as many dialects of those. For
+language-specific information, please see the corresponding language
+specific section:</p>
+<ul class="simple">
+<li><a class="reference internal" href="#c"><span class="std std-ref">C Language</span></a>: K&R C, ANSI C89, ISO C90, ISO C94 (C89+AMD1), ISO
+C99 (+TC1, TC2, TC3).</li>
+<li><a class="reference internal" href="#objc"><span class="std std-ref">Objective-C Language</span></a>: ObjC 1, ObjC 2, ObjC 2.1, plus
+variants depending on base language.</li>
+<li><a class="reference internal" href="#cxx"><span class="std std-ref">C++ Language</span></a></li>
+<li><a class="reference internal" href="#objcxx"><span class="std std-ref">Objective C++ Language</span></a></li>
+<li><a class="reference internal" href="#opencl"><span class="std std-ref">OpenCL C Language</span></a>: v1.0, v1.1, v1.2, v2.0.</li>
+</ul>
+<p>In addition to these base languages and their dialects, Clang supports a
+broad variety of language extensions, which are documented in the
+corresponding language section. These extensions are provided to be
+compatible with the GCC, Microsoft, and other popular compilers as well
+as to improve functionality through Clang-specific features. The Clang
+driver and language features are intentionally designed to be as
+compatible with the GNU GCC compiler as reasonably possible, easing
+migration from GCC to Clang. In most cases, code âjust worksâ.
+Clang also provides an alternative driver, <a class="reference internal" href="#clang-cl"><span class="std std-ref">clang-cl</span></a>, that is designed
+to be compatible with the Visual C++ compiler, cl.exe.</p>
+<p>In addition to language specific features, Clang has a variety of
+features that depend on what CPU architecture or operating system is
+being compiled for. Please see the <a class="reference internal" href="#target-features"><span class="std std-ref">Target-Specific Features and
+Limitations</span></a> section for more details.</p>
+<p>The rest of the introduction introduces some basic <a class="reference internal" href="#terminology"><span class="std std-ref">compiler
+terminology</span></a> that is used throughout this manual and
+contains a basic <a class="reference internal" href="#basicusage"><span class="std std-ref">introduction to using Clang</span></a> as a
+command line compiler.</p>
+<div class="section" id="terminology">
+<span id="id1"></span><h3><a class="toc-backref" href="#id11">Terminology</a><a class="headerlink" href="#terminology" title="Permalink to this headline">¶</a></h3>
+<p>Front end, parser, backend, preprocessor, undefined behavior,
+diagnostic, optimizer</p>
+</div>
+<div class="section" id="basic-usage">
+<span id="basicusage"></span><h3><a class="toc-backref" href="#id12">Basic Usage</a><a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h3>
+<p>Intro to how to use a C compiler for newbies.</p>
+<p>compile + link compile then link debug info enabling optimizations
+picking a language to use, defaults to C11 by default. Autosenses based
+on extension. using a makefile</p>
+</div>
+</div>
+<div class="section" id="command-line-options">
+<h2><a class="toc-backref" href="#id13">Command Line Options</a><a class="headerlink" href="#command-line-options" title="Permalink to this headline">¶</a></h2>
+<p>This section is generally an index into other sections. It does not go
+into depth on the ones that are covered by other sections. However, the
+first part introduces the language selection and other high level
+options like <a class="reference internal" href="CommandGuide/clang.html#cmdoption-c"><code class="xref std std-option docutils literal notranslate"><span class="pre">-c</span></code></a>, <a class="reference internal" href="#cmdoption-g"><code class="xref std std-option docutils literal notranslate"><span class="pre">-g</span></code></a>, etc.</p>
+<div class="section" id="options-to-control-error-and-warning-messages">
+<h3><a class="toc-backref" href="#id14">Options to Control Error and Warning Messages</a><a class="headerlink" href="#options-to-control-error-and-warning-messages" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-werror">
+<code class="descname">-Werror</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-werror" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turn warnings into errors.</p>
+</dd></dl>
+
+<p><code class="docutils literal notranslate"><span class="pre">-Werror=foo</span></code></p>
+<blockquote>
+<div>Turn warning âfooâ into an error.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-wno-error">
+<code class="descname">-Wno-error</code><code class="descclassname">=foo</code><a class="headerlink" href="#cmdoption-wno-error" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turn warning âfooâ into a warning even if <a class="reference internal" href="#cmdoption-werror"><code class="xref std std-option docutils literal notranslate"><span class="pre">-Werror</span></code></a> is specified.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-wfoo">
+<code class="descname">-Wfoo</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-wfoo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable warning âfooâ.
+See the <a class="reference internal" href="DiagnosticsReference.html"><span class="doc">diagnostics reference</span></a> for a complete
+list of the warning flags that can be specified in this way.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-wno-foo">
+<code class="descname">-Wno-foo</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-wno-foo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable warning âfooâ.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-w">
+<code class="descname">-w</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-w" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable all diagnostics.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-weverything">
+<code class="descname">-Weverything</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-weverything" title="Permalink to this definition">¶</a></dt>
+<dd><p><a class="reference internal" href="#diagnostics-enable-everything"><span class="std std-ref">Enable all diagnostics.</span></a></p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pedantic">
+<code class="descname">-pedantic</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-pedantic" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn on language extensions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pedantic-errors">
+<code class="descname">-pedantic-errors</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-pedantic-errors" title="Permalink to this definition">¶</a></dt>
+<dd><p>Error on language extensions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-wsystem-headers">
+<code class="descname">-Wsystem-headers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-wsystem-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable warnings from system headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ferror-limit">
+<code class="descname">-ferror-limit</code><code class="descclassname">=123</code><a class="headerlink" href="#cmdoption-ferror-limit" title="Permalink to this definition">¶</a></dt>
+<dd><p>Stop emitting diagnostics after 123 errors have been produced. The default is
+20, and the error limit can be disabled with <cite>-ferror-limit=0</cite>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftemplate-backtrace-limit">
+<code class="descname">-ftemplate-backtrace-limit</code><code class="descclassname">=123</code><a class="headerlink" href="#cmdoption-ftemplate-backtrace-limit" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only emit up to 123 template instantiation notes within the template
+instantiation backtrace for a single warning or error. The default is 10, and
+the limit can be disabled with <cite>-ftemplate-backtrace-limit=0</cite>.</p>
+</dd></dl>
+
+<div class="section" id="formatting-of-diagnostics">
+<span id="cl-diag-formatting"></span><h4><a class="toc-backref" href="#id15">Formatting of Diagnostics</a><a class="headerlink" href="#formatting-of-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>Clang aims to produce beautiful diagnostics by default, particularly for
+new users that first come to Clang. However, different people have
+different preferences, and sometimes Clang is driven not by a human,
+but by a program that wants consistent and easily parsable output. For
+these cases, Clang provides a wide range of options to control the exact
+output format of the diagnostics that it generates.</p>
+<dl class="docutils" id="opt-fshow-column">
+<dt><strong>-f[no-]show-column</strong></dt>
+<dd><p class="first">Print column number in diagnostic.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the column number of a diagnostic. For example, when this is
+enabled, Clang will print something like:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</pre></div>
+</div>
+<p>When this is disabled, Clang will print âtest.c:28: warningâ¦â with
+no column number.</p>
+<p class="last">The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fshow-source-location">
+<dt><strong>-f[no-]show-source-location</strong></dt>
+<dd><p class="first">Print source file/line/column information in diagnostic.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the filename, line number and column number of a diagnostic.
+For example, when this is enabled, Clang will print something like:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</pre></div>
+</div>
+<p class="last">When this is disabled, Clang will not print the âtest.c:28:8: â
+part.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fcaret-diagnostics">
+<dt><strong>-f[no-]caret-diagnostics</strong></dt>
+<dd><p class="first">Print source line and ranges from source code in diagnostic.
+This option, which defaults to on, controls whether or not Clang
+prints the source line, source ranges, and caret when emitting a
+diagnostic. For example, when this is enabled, Clang will print
+something like:</p>
+<div class="last highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</pre></div>
+</div>
+</dd>
+<dt><strong>-f[no-]color-diagnostics</strong></dt>
+<dd><p class="first">This option, which defaults to on when a color-capable terminal is
+detected, controls whether or not Clang prints diagnostics in color.</p>
+<p>When this option is enabled, Clang will use colors to highlight
+specific parts of the diagnostic, e.g.,</p>
+<pre>
+ <b><span style="color:black">test.c:28:8: <span style="color:magenta">warning</span>: extra tokens at end of #endif directive [-Wextra-tokens]</span></b>
+ #endif bad
+ <span style="color:green">^</span>
+ <span style="color:green">//</span>
+</pre><p>When this is disabled, Clang will just print:</p>
+<div class="last highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">2</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</pre></div>
+</div>
+</dd>
+<dt><strong>-fansi-escape-codes</strong></dt>
+<dd>Controls whether ANSI escape codes are used instead of the Windows Console
+API to output colored diagnostics. This option is only used on Windows and
+defaults to off.</dd>
+</dl>
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-format">
+<code class="descname">-fdiagnostics-format</code><code class="descclassname">=clang/msvc/vi</code><a class="headerlink" href="#cmdoption-fdiagnostics-format" title="Permalink to this definition">¶</a></dt>
+<dd><p>Changes diagnostic output format to better match IDEs and command line tools.</p>
+<p>This option controls the output format of the filename, line number,
+and column printed in diagnostic messages. The options, and their
+affect on formatting a simple conversion diagnostic, follow:</p>
+<dl class="docutils">
+<dt><strong>clang</strong> (default)</dt>
+<dd><div class="first last highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">3</span><span class="p">:</span><span class="mi">11</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span>
+</pre></div>
+</div>
+</dd>
+<dt><strong>msvc</strong></dt>
+<dd><div class="first last highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span><span class="mi">11</span><span class="p">)</span> <span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span>
+</pre></div>
+</div>
+</dd>
+<dt><strong>vi</strong></dt>
+<dd><div class="first last highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">c</span> <span class="o">+</span><span class="mi">3</span><span class="p">:</span><span class="mi">11</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span>
+</pre></div>
+</div>
+</dd>
+</dl>
+</dd></dl>
+
+<dl class="docutils" id="opt-fdiagnostics-show-option">
+<dt><strong>-f[no-]diagnostics-show-option</strong></dt>
+<dd><p class="first">Enable <code class="docutils literal notranslate"><span class="pre">[-Woption]</span></code> information in diagnostic line.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the associated <a class="reference internal" href="#cl-diag-warning-groups"><span class="std std-ref">warning group</span></a>
+option name when outputting a warning diagnostic. For example, in
+this output:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</pre></div>
+</div>
+<p class="last">Passing <strong>-fno-diagnostics-show-option</strong> will prevent Clang from
+printing the [<a class="reference internal" href="#opt-wextra-tokens"><span class="std std-ref">-Wextra-tokens</span></a>] information in
+the diagnostic. This information tells you the flag needed to enable
+or disable the diagnostic, either from the command line or through
+<a class="reference internal" href="#pragma-gcc-diagnostic"><span class="std std-ref">#pragma GCC diagnostic</span></a>.</p>
+</dd>
+</dl>
+<span class="target" id="opt-fdiagnostics-show-category"></span><dl class="option">
+<dt id="cmdoption-fdiagnostics-show-category">
+<code class="descname">-fdiagnostics-show-category</code><code class="descclassname">=none/id/name</code><a class="headerlink" href="#cmdoption-fdiagnostics-show-category" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable printing category information in diagnostic line.</p>
+<p>This option, which defaults to ânoneâ, controls whether or not Clang
+prints the category associated with a diagnostic when emitting it.
+Each diagnostic may or many not have an associated category, if it
+has one, it is listed in the diagnostic categorization field of the
+diagnostic line (in the []âs).</p>
+<p>For example, a format string warning will produce these three
+renditions based on the setting of this option:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">3</span><span class="p">:</span><span class="mi">11</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span> <span class="p">[</span><span class="o">-</span><span class="n">Wformat</span><span class="p">]</span>
+<span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">3</span><span class="p">:</span><span class="mi">11</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span> <span class="p">[</span><span class="o">-</span><span class="n">Wformat</span><span class="p">,</span><span class="mi">1</span><span class="p">]</span>
+<span class="n">t</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">3</span><span class="p">:</span><span class="mi">11</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">conversion</span> <span class="n">specifies</span> <span class="nb">type</span> <span class="s1">'char *'</span> <span class="n">but</span> <span class="n">the</span> <span class="n">argument</span> <span class="n">has</span> <span class="nb">type</span> <span class="s1">'int'</span> <span class="p">[</span><span class="o">-</span><span class="n">Wformat</span><span class="p">,</span><span class="n">Format</span> <span class="n">String</span><span class="p">]</span>
+</pre></div>
+</div>
+<p>This category can be used by clients that want to group diagnostics
+by category, so it should be a high level category. We want dozens
+of these, not hundreds or thousands of them.</p>
+</dd></dl>
+
+<span class="target" id="opt-fsave-optimization-record"></span><dl class="option">
+<dt id="cmdoption-fsave-optimization-record">
+<code class="descname">-fsave-optimization-record[</code><code class="descclassname">=<format>]</code><a class="headerlink" href="#cmdoption-fsave-optimization-record" title="Permalink to this definition">¶</a></dt>
+<dd><p>Write optimization remarks to a separate file.</p>
+<p>This option, which defaults to off, controls whether Clang writes
+optimization reports to a separate file. By recording diagnostics in a file,
+users can parse or sort the remarks in a convenient way.</p>
+<p>By default, the serialization format is YAML.</p>
+<p>The supported serialization formats are:</p>
+<ul class="simple">
+<li><p id="opt-fsave-optimization-record-yaml"><code class="docutils literal notranslate"><span class="pre">-fsave-optimization-record=yaml</span></code>: A structured YAML format.</p>
+</li>
+</ul>
+</dd></dl>
+
+<dl class="docutils" id="opt-foptimization-record-file">
+<dt><strong>-foptimization-record-file</strong></dt>
+<dd><p class="first">Control the file to which optimization reports are written.</p>
+<p>When optimization reports are being output (see
+<a class="reference internal" href="#opt-fsave-optimization-record"><span class="std std-ref">-fsave-optimization-record</span></a>), this
+option controls the file to which those reports are written.</p>
+<p class="last">If this option is not used, optimization records are output to a file named
+after the primary file being compiled. If thatâs âfoo.câ, for example,
+optimization records are output to âfoo.opt.yamlâ. If a specific
+serialization format is specified, the file will be named
+âfoo.opt.<format>â.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-foptimization-record-passes">
+<dt><strong>-foptimization-record-passes</strong></dt>
+<dd><p class="first">Only include passes which match a specified regular expression.</p>
+<p>When optimization reports are being output (see
+<a class="reference internal" href="#opt-fsave-optimization-record"><span class="std std-ref">-fsave-optimization-record</span></a>), this
+option controls the passes that will be included in the final report.</p>
+<p class="last">If this option is not used, all the passes are included in the optimization
+record.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fdiagnostics-show-hotness">
+<dt><strong>-f[no-]diagnostics-show-hotness</strong></dt>
+<dd><p class="first">Enable profile hotness information in diagnostic line.</p>
+<p>This option controls whether Clang prints the profile hotness associated
+with diagnostics in the presence of profile-guided optimization information.
+This is currently supported with optimization remarks (see
+<a class="reference internal" href="#rpass"><span class="std std-ref">Options to Emit Optimization Reports</span></a>). The hotness information
+allows users to focus on the hot optimization remarks that are likely to be
+more relevant for run-time performance.</p>
+<p>For example, in this output, the block containing the callsite of <cite>foo</cite> was
+executed 3000 times according to the profile data:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">s</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">7</span><span class="p">:</span><span class="mi">10</span><span class="p">:</span> <span class="n">remark</span><span class="p">:</span> <span class="n">foo</span> <span class="n">inlined</span> <span class="n">into</span> <span class="n">bar</span> <span class="p">(</span><span class="n">hotness</span><span class="p">:</span> <span class="mi">3000</span><span class="p">)</span> <span class="p">[</span><span class="o">-</span><span class="n">Rpass</span><span class="o">-</span><span class="n">analysis</span><span class="o">=</span><span class="n">inline</span><span class="p">]</span>
+ <span class="nb">sum</span> <span class="o">+=</span> <span class="n">foo</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">x</span> <span class="o">-</span> <span class="mi">2</span><span class="p">);</span>
+ <span class="o">^</span>
+</pre></div>
+</div>
+<p class="last">This option is implied when
+<a class="reference internal" href="#opt-fsave-optimization-record"><span class="std std-ref">-fsave-optimization-record</span></a> is used.
+Otherwise, it defaults to off.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fdiagnostics-hotness-threshold">
+<dt><strong>-fdiagnostics-hotness-threshold</strong></dt>
+<dd><p class="first">Prevent optimization remarks from being output if they do not have at least
+this hotness value.</p>
+<p class="last">This option, which defaults to zero, controls the minimum hotness an
+optimization remark would need in order to be output by Clang. This is
+currently supported with optimization remarks (see <a class="reference internal" href="#rpass"><span class="std std-ref">Options to Emit
+Optimization Reports</span></a>) when profile hotness information in
+diagnostics is enabled (see
+<a class="reference internal" href="#opt-fdiagnostics-show-hotness"><span class="std std-ref">-fdiagnostics-show-hotness</span></a>).</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fdiagnostics-fixit-info">
+<dt><strong>-f[no-]diagnostics-fixit-info</strong></dt>
+<dd><p class="first">Enable âFixItâ information in the diagnostics output.</p>
+<p>This option, which defaults to on, controls whether or not Clang
+prints the information on how to fix a specific diagnostic
+underneath it when it knows. For example, in this output:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+ <span class="o">//</span>
+</pre></div>
+</div>
+<p class="last">Passing <strong>-fno-diagnostics-fixit-info</strong> will prevent Clang from
+printing the â//â line at the end of the message. This information
+is useful for users who may not understand what is wrong, but can be
+confusing for machine parsing.</p>
+</dd>
+</dl>
+<dl class="docutils" id="opt-fdiagnostics-print-source-range-info">
+<dt><strong>-fdiagnostics-print-source-range-info</strong></dt>
+<dd><p class="first">Print machine parsable information about source ranges.
+This option makes Clang print information about source ranges in a machine
+parsable format after the file/line/column number information. The
+information is a simple sequence of brace enclosed ranges, where each range
+lists the start and end line/column locations. For example, in this output:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">exprs</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">47</span><span class="p">:</span><span class="mi">15</span><span class="p">:{</span><span class="mi">47</span><span class="p">:</span><span class="mi">8</span><span class="o">-</span><span class="mi">47</span><span class="p">:</span><span class="mi">14</span><span class="p">}{</span><span class="mi">47</span><span class="p">:</span><span class="mi">17</span><span class="o">-</span><span class="mi">47</span><span class="p">:</span><span class="mi">24</span><span class="p">}:</span> <span class="n">error</span><span class="p">:</span> <span class="n">invalid</span> <span class="n">operands</span> <span class="n">to</span> <span class="n">binary</span> <span class="n">expression</span> <span class="p">(</span><span class="s1">'int *'</span> <span class="ow">and</span> <span class="s1">'_Complex float'</span><span class="p">)</span>
+ <span class="n">P</span> <span class="o">=</span> <span class="p">(</span><span class="n">P</span><span class="o">-</span><span class="mi">42</span><span class="p">)</span> <span class="o">+</span> <span class="n">Gamma</span><span class="o">*</span><span class="mi">4</span><span class="p">;</span>
+ <span class="o">~~~~~~</span> <span class="o">^</span> <span class="o">~~~~~~~</span>
+</pre></div>
+</div>
+<p>The {}âs are generated by -fdiagnostics-print-source-range-info.</p>
+<p class="last">The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd>
+</dl>
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-parseable-fixits">
+<code class="descname">-fdiagnostics-parseable-fixits</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fdiagnostics-parseable-fixits" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print Fix-Its in a machine parseable form.</p>
+<p>This option makes Clang print available Fix-Its in a machine
+parseable format at the end of diagnostics. The following example
+illustrates the format:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fix</span><span class="o">-</span><span class="n">it</span><span class="p">:</span><span class="s2">"t.cpp"</span><span class="p">:{</span><span class="mi">7</span><span class="p">:</span><span class="mi">25</span><span class="o">-</span><span class="mi">7</span><span class="p">:</span><span class="mi">29</span><span class="p">}:</span><span class="s2">"Gamma"</span>
+</pre></div>
+</div>
+<p>The range printed is a half-open range, so in this example the
+characters at column 25 up to but not including column 29 on line 7
+in t.cpp should be replaced with the string âGammaâ. Either the
+range or the replacement string may be empty (representing strict
+insertions and strict erasures, respectively). Both the file name
+and the insertion string escape backslash (as â\â), tabs (as
+â\tâ), newlines (as â\nâ), double quotes(as â"â) and
+non-printable characters (as octal â\xxxâ).</p>
+<p>The printed column numbers count bytes from the beginning of the
+line; take care if your source contains multibyte characters.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-elide-type">
+<code class="descname">-fno-elide-type</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fno-elide-type" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turns off elision in template type printing.</p>
+<p>The default for template type printing is to elide as many template
+arguments as possible, removing those which are the same in both
+template types, leaving only the differences. Adding this flag will
+print all the template arguments. If supported by the terminal,
+highlighting will still appear on differing arguments.</p>
+<p>Default:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">cc</span><span class="p">:</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">:</span> <span class="n">note</span><span class="p">:</span> <span class="n">candidate</span> <span class="n">function</span> <span class="ow">not</span> <span class="n">viable</span><span class="p">:</span> <span class="n">no</span> <span class="n">known</span> <span class="n">conversion</span> <span class="kn">from</span> <span class="s1">'vector<map<[...], map<float, [...]>>>'</span> <span class="n">to</span> <span class="s1">'vector<map<[...], map<double, [...]>>>'</span> <span class="k">for</span> <span class="mi">1</span><span class="n">st</span> <span class="n">argument</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>-fno-elide-type:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">cc</span><span class="p">:</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">:</span> <span class="n">note</span><span class="p">:</span> <span class="n">candidate</span> <span class="n">function</span> <span class="ow">not</span> <span class="n">viable</span><span class="p">:</span> <span class="n">no</span> <span class="n">known</span> <span class="n">conversion</span> <span class="kn">from</span> <span class="s1">'vector<map<int, map<float, int>>>'</span> <span class="n">to</span> <span class="s1">'vector<map<int, map<double, int>>>'</span> <span class="k">for</span> <span class="mi">1</span><span class="n">st</span> <span class="n">argument</span><span class="p">;</span>
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-show-template-tree">
+<code class="descname">-fdiagnostics-show-template-tree</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fdiagnostics-show-template-tree" title="Permalink to this definition">¶</a></dt>
+<dd><p>Template type diffing prints a text tree.</p>
+<p>For diffing large templated types, this option will cause Clang to
+display the templates as an indented text tree, one argument per
+line, with differences marked inline. This is compatible with
+-fno-elide-type.</p>
+<p>Default:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">cc</span><span class="p">:</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">:</span> <span class="n">note</span><span class="p">:</span> <span class="n">candidate</span> <span class="n">function</span> <span class="ow">not</span> <span class="n">viable</span><span class="p">:</span> <span class="n">no</span> <span class="n">known</span> <span class="n">conversion</span> <span class="kn">from</span> <span class="s1">'vector<map<[...], map<float, [...]>>>'</span> <span class="n">to</span> <span class="s1">'vector<map<[...], map<double, [...]>>>'</span> <span class="k">for</span> <span class="mi">1</span><span class="n">st</span> <span class="n">argument</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>With <a class="reference internal" href="#cmdoption-fdiagnostics-show-template-tree"><code class="xref std std-option docutils literal notranslate"><span class="pre">-fdiagnostics-show-template-tree</span></code></a>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">t</span><span class="o">.</span><span class="n">cc</span><span class="p">:</span><span class="mi">4</span><span class="p">:</span><span class="mi">5</span><span class="p">:</span> <span class="n">note</span><span class="p">:</span> <span class="n">candidate</span> <span class="n">function</span> <span class="ow">not</span> <span class="n">viable</span><span class="p">:</span> <span class="n">no</span> <span class="n">known</span> <span class="n">conversion</span> <span class="k">for</span> <span class="mi">1</span><span class="n">st</span> <span class="n">argument</span><span class="p">;</span>
+ <span class="n">vector</span><span class="o"><</span>
+ <span class="nb">map</span><span class="o"><</span>
+ <span class="p">[</span><span class="o">...</span><span class="p">],</span>
+ <span class="nb">map</span><span class="o"><</span>
+ <span class="p">[</span><span class="nb">float</span> <span class="o">!=</span> <span class="n">double</span><span class="p">],</span>
+ <span class="p">[</span><span class="o">...</span><span class="p">]</span><span class="o">>>></span>
+</pre></div>
+</div>
+</dd></dl>
+
+</div>
+<div class="section" id="individual-warning-groups">
+<span id="cl-diag-warning-groups"></span><h4><a class="toc-backref" href="#id16">Individual Warning Groups</a><a class="headerlink" href="#individual-warning-groups" title="Permalink to this headline">¶</a></h4>
+<p>TODO: Generate this from tblgen. Define one anchor per warning group.</p>
+<span class="target" id="opt-wextra-tokens"></span><dl class="option">
+<dt id="cmdoption-wextra-tokens">
+<code class="descname">-Wextra-tokens</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-wextra-tokens" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn about excess tokens at the end of a preprocessor directive.</p>
+<p>This option, which defaults to on, enables warnings about extra
+tokens at the end of preprocessor directives. For example:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">test</span><span class="o">.</span><span class="n">c</span><span class="p">:</span><span class="mi">28</span><span class="p">:</span><span class="mi">8</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">extra</span> <span class="n">tokens</span> <span class="n">at</span> <span class="n">end</span> <span class="n">of</span> <span class="c1">#endif directive [-Wextra-tokens]</span>
+<span class="c1">#endif bad</span>
+ <span class="o">^</span>
+</pre></div>
+</div>
+<p>These extra tokens are not strictly conforming, and are usually best
+handled by commenting them out.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-wambiguous-member-template">
+<code class="descname">-Wambiguous-member-template</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-wambiguous-member-template" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn about unqualified uses of a member template whose name resolves to
+another template at the location of the use.</p>
+<p>This option, which defaults to on, enables a warning in the
+following code:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">template</span><span class="o"><</span><span class="n">typename</span> <span class="n">T</span><span class="o">></span> <span class="n">struct</span> <span class="nb">set</span><span class="p">{};</span>
+<span class="n">template</span><span class="o"><</span><span class="n">typename</span> <span class="n">T</span><span class="o">></span> <span class="n">struct</span> <span class="n">trait</span> <span class="p">{</span> <span class="n">typedef</span> <span class="n">const</span> <span class="n">T</span><span class="o">&</span> <span class="nb">type</span><span class="p">;</span> <span class="p">};</span>
+<span class="n">struct</span> <span class="n">Value</span> <span class="p">{</span>
+ <span class="n">template</span><span class="o"><</span><span class="n">typename</span> <span class="n">T</span><span class="o">></span> <span class="n">void</span> <span class="nb">set</span><span class="p">(</span><span class="n">typename</span> <span class="n">trait</span><span class="o"><</span><span class="n">T</span><span class="o">></span><span class="p">::</span><span class="nb">type</span> <span class="n">value</span><span class="p">)</span> <span class="p">{}</span>
+<span class="p">};</span>
+<span class="n">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">Value</span> <span class="n">v</span><span class="p">;</span>
+ <span class="n">v</span><span class="o">.</span><span class="n">set</span><span class="o"><</span><span class="n">double</span><span class="o">></span><span class="p">(</span><span class="mf">3.2</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>C++ [basic.lookup.classref] requires this to be an error, but,
+because itâs hard to work around, Clang downgrades it to a warning
+as an extension.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-wbind-to-temporary-copy">
+<code class="descname">-Wbind-to-temporary-copy</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-wbind-to-temporary-copy" title="Permalink to this definition">¶</a></dt>
+<dd><p>Warn about an unusable copy constructor when binding a reference to a
+temporary.</p>
+<p>This option enables warnings about binding a
+reference to a temporary when the temporary doesnât have a usable
+copy constructor. For example:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">struct</span> <span class="n">NonCopyable</span> <span class="p">{</span>
+ <span class="n">NonCopyable</span><span class="p">();</span>
+<span class="n">private</span><span class="p">:</span>
+ <span class="n">NonCopyable</span><span class="p">(</span><span class="n">const</span> <span class="n">NonCopyable</span><span class="o">&</span><span class="p">);</span>
+<span class="p">};</span>
+<span class="n">void</span> <span class="n">foo</span><span class="p">(</span><span class="n">const</span> <span class="n">NonCopyable</span><span class="o">&</span><span class="p">);</span>
+<span class="n">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">(</span><span class="n">NonCopyable</span><span class="p">());</span> <span class="o">//</span> <span class="n">Disallowed</span> <span class="ow">in</span> <span class="n">C</span><span class="o">++</span><span class="mi">98</span><span class="p">;</span> <span class="n">allowed</span> <span class="ow">in</span> <span class="n">C</span><span class="o">++</span><span class="mf">11.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">struct</span> <span class="n">NonCopyable2</span> <span class="p">{</span>
+ <span class="n">NonCopyable2</span><span class="p">();</span>
+ <span class="n">NonCopyable2</span><span class="p">(</span><span class="n">NonCopyable2</span><span class="o">&</span><span class="p">);</span>
+<span class="p">};</span>
+<span class="n">void</span> <span class="n">foo</span><span class="p">(</span><span class="n">const</span> <span class="n">NonCopyable2</span><span class="o">&</span><span class="p">);</span>
+<span class="n">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">(</span><span class="n">NonCopyable2</span><span class="p">());</span> <span class="o">//</span> <span class="n">Disallowed</span> <span class="ow">in</span> <span class="n">C</span><span class="o">++</span><span class="mi">98</span><span class="p">;</span> <span class="n">allowed</span> <span class="ow">in</span> <span class="n">C</span><span class="o">++</span><span class="mf">11.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that if <code class="docutils literal notranslate"><span class="pre">NonCopyable2::NonCopyable2()</span></code> has a default argument
+whose instantiation produces a compile error, that error will still
+be a hard error in C++98 mode even if this warning is turned off.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="options-to-control-clang-crash-diagnostics">
+<h3><a class="toc-backref" href="#id17">Options to Control Clang Crash Diagnostics</a><a class="headerlink" href="#options-to-control-clang-crash-diagnostics" title="Permalink to this headline">¶</a></h3>
+<p>As unbelievable as it may sound, Clang does crash from time to time.
+Generally, this only occurs to those living on the <a class="reference external" href="https://llvm.org/releases/download.html#svn">bleeding
+edge</a>. Clang goes to great
+lengths to assist you in filing a bug report. Specifically, Clang
+generates preprocessed source file(s) and associated run script(s) upon
+a crash. These files should be attached to a bug report to ease
+reproducibility of the failure. Below are the command line options to
+control the crash diagnostics.</p>
+<dl class="option">
+<dt id="cmdoption-fno-crash-diagnostics">
+<code class="descname">-fno-crash-diagnostics</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fno-crash-diagnostics" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable auto-generation of preprocessed source files during a clang crash.</p>
+</dd></dl>
+
+<p>The -fno-crash-diagnostics flag can be helpful for speeding the process
+of generating a delta reduced test case.</p>
+<p>Clang is also capable of generating preprocessed source file(s) and associated
+run script(s) even without a crash. This is specially useful when trying to
+generate a reproducer for warnings or errors while using modules.</p>
+<dl class="option">
+<dt id="cmdoption-gen-reproducer">
+<code class="descname">-gen-reproducer</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-gen-reproducer" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generates preprocessed source files, a reproducer script and if relevant, a
+cache containing: built module pcmâs and all headers needed to rebuilt the
+same modules.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="options-to-emit-optimization-reports">
+<span id="rpass"></span><h3><a class="toc-backref" href="#id18">Options to Emit Optimization Reports</a><a class="headerlink" href="#options-to-emit-optimization-reports" title="Permalink to this headline">¶</a></h3>
+<p>Optimization reports trace, at a high-level, all the major decisions
+done by compiler transformations. For instance, when the inliner
+decides to inline function <code class="docutils literal notranslate"><span class="pre">foo()</span></code> into <code class="docutils literal notranslate"><span class="pre">bar()</span></code>, or the loop unroller
+decides to unroll a loop N times, or the vectorizer decides to
+vectorize a loop body.</p>
+<p>Clang offers a family of flags which the optimizers can use to emit
+a diagnostic in three cases:</p>
+<ol class="arabic simple">
+<li>When the pass makes a transformation (<cite>-Rpass</cite>).</li>
+<li>When the pass fails to make a transformation (<cite>-Rpass-missed</cite>).</li>
+<li>When the pass determines whether or not to make a transformation
+(<cite>-Rpass-analysis</cite>).</li>
+</ol>
+<p>NOTE: Although the discussion below focuses on <cite>-Rpass</cite>, the exact
+same options apply to <cite>-Rpass-missed</cite> and <cite>-Rpass-analysis</cite>.</p>
+<p>Since there are dozens of passes inside the compiler, each of these flags
+take a regular expression that identifies the name of the pass which should
+emit the associated diagnostic. For example, to get a report from the inliner,
+compile the code with:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -O2 -Rpass<span class="o">=</span>inline code.cc -o code
+<span class="go">code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]</span>
+<span class="go">int bar(int j) { return foo(j, j - 2); }</span>
+<span class="go"> ^</span>
+</pre></div>
+</div>
+<p>Note that remarks from the inliner are identified with <cite>[-Rpass=inline]</cite>.
+To request a report from every optimization pass, you should use
+<cite>-Rpass=.*</cite> (in fact, you can use any valid POSIX regular
+expression). However, do not expect a report from every transformation
+made by the compiler. Optimization remarks do not really make sense
+outside of the major transformations (e.g., inlining, vectorization,
+loop optimizations) and not every optimization pass supports this
+feature.</p>
+<p>Note that when using profile-guided optimization information, profile hotness
+information can be included in the remarks (see
+<a class="reference internal" href="#opt-fdiagnostics-show-hotness"><span class="std std-ref">-fdiagnostics-show-hotness</span></a>).</p>
+<div class="section" id="current-limitations">
+<h4><a class="toc-backref" href="#id19">Current limitations</a><a class="headerlink" href="#current-limitations" title="Permalink to this headline">¶</a></h4>
+<ol class="arabic simple">
+<li>Optimization remarks that refer to function names will display the
+mangled name of the function. Since these remarks are emitted by the
+back end of the compiler, it does not know anything about the input
+language, nor its mangling rules.</li>
+<li>Some source locations are not displayed correctly. The front end has
+a more detailed source location tracking than the locations included
+in the debug info (e.g., the front end can locate code inside macro
+expansions). However, the locations used by <cite>-Rpass</cite> are
+translated from debug annotations. That translation can be lossy,
+which results in some remarks having no location information.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="other-options">
+<h3><a class="toc-backref" href="#id20">Other Options</a><a class="headerlink" href="#other-options" title="Permalink to this headline">¶</a></h3>
+<p>Clang options that donât fit neatly into other categories.</p>
+<dl class="option">
+<dt id="cmdoption-mv">
+<code class="descname">-MV</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-mv" title="Permalink to this definition">¶</a></dt>
+<dd><p>When emitting a dependency file, use formatting conventions appropriate
+for NMake or Jom. Ignored unless another option causes Clang to emit a
+dependency file.</p>
+</dd></dl>
+
+<p>When Clang emits a dependency file (e.g., you supplied the -M option)
+most filenames can be written to the file without any special formatting.
+Different Make tools will treat different sets of characters as âspecialâ
+and use different conventions for telling the Make tool that the character
+is actually part of the filename. Normally Clang uses backslash to âescapeâ
+a special character, which is the convention used by GNU Make. The -MV
+option tells Clang to put double-quotes around the entire filename, which
+is the convention used by NMake and Jom.</p>
+</div>
+<div class="section" id="configuration-files">
+<h3><a class="toc-backref" href="#id21">Configuration files</a><a class="headerlink" href="#configuration-files" title="Permalink to this headline">¶</a></h3>
+<p>Configuration files group command-line options and allow all of them to be
+specified just by referencing the configuration file. They may be used, for
+example, to collect options required to tune compilation for particular
+target, such as -L, -I, -l, âsysroot, codegen options, etc.</p>
+<p>The command line option <cite>âconfig</cite> can be used to specify configuration
+file in a Clang invocation. For example:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">clang</span> <span class="o">--</span><span class="n">config</span> <span class="o">/</span><span class="n">home</span><span class="o">/</span><span class="n">user</span><span class="o">/</span><span class="n">cfgs</span><span class="o">/</span><span class="n">testing</span><span class="o">.</span><span class="n">txt</span>
+<span class="n">clang</span> <span class="o">--</span><span class="n">config</span> <span class="n">debug</span><span class="o">.</span><span class="n">cfg</span>
+</pre></div>
+</div>
+<p>If the provided argument contains a directory separator, it is considered as
+a file path, and options are read from that file. Otherwise the argument is
+treated as a file name and is searched for sequentially in the directories:</p>
+<blockquote>
+<div><ul class="simple">
+<li>user directory,</li>
+<li>system directory,</li>
+<li>the directory where Clang executable resides.</li>
+</ul>
+</div></blockquote>
+<p>Both user and system directories for configuration files are specified during
+clang build using CMake parameters, CLANG_CONFIG_FILE_USER_DIR and
+CLANG_CONFIG_FILE_SYSTEM_DIR respectively. The first file found is used. It is
+an error if the required file cannot be found.</p>
+<p>Another way to specify a configuration file is to encode it in executable name.
+For example, if the Clang executable is named <cite>armv7l-clang</cite> (it may be a
+symbolic link to <cite>clang</cite>), then Clang will search for file <cite>armv7l.cfg</cite> in the
+directory where Clang resides.</p>
+<p>If a driver mode is specified in invocation, Clang tries to find a file specific
+for the specified mode. For example, if the executable file is named
+<cite>x86_64-clang-cl</cite>, Clang first looks for <cite>x86_64-cl.cfg</cite> and if it is not found,
+looks for <cite>x86_64.cfg</cite>.</p>
+<p>If the command line contains options that effectively change target architecture
+(these are -m32, -EL, and some others) and the configuration file starts with an
+architecture name, Clang tries to load the configuration file for the effective
+architecture. For example, invocation:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">x86_64</span><span class="o">-</span><span class="n">clang</span> <span class="o">-</span><span class="n">m32</span> <span class="n">abc</span><span class="o">.</span><span class="n">c</span>
+</pre></div>
+</div>
+<p>causes Clang search for a file <cite>i368.cfg</cite> first, and if no such file is found,
+Clang looks for the file <cite>x86_64.cfg</cite>.</p>
+<p>The configuration file consists of command-line options specified on one or
+more lines. Lines composed of whitespace characters only are ignored as well as
+lines in which the first non-blank character is <cite>#</cite>. Long options may be split
+between several lines by a trailing backslash. Here is example of a
+configuration file:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Several options on line</span>
+<span class="o">-</span><span class="n">c</span> <span class="o">--</span><span class="n">target</span><span class="o">=</span><span class="n">x86_64</span><span class="o">-</span><span class="n">unknown</span><span class="o">-</span><span class="n">linux</span><span class="o">-</span><span class="n">gnu</span>
+
+<span class="c1"># Long option split between lines</span>
+<span class="o">-</span><span class="n">I</span><span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">gcc</span><span class="o">/</span><span class="n">x86_64</span><span class="o">-</span><span class="n">linux</span><span class="o">-</span><span class="n">gnu</span><span class="o">/</span><span class="mf">5.4</span><span class="o">.</span><span class="mi">0</span><span class="o">/../../../../</span>\
+<span class="n">include</span><span class="o">/</span><span class="n">c</span><span class="o">++/</span><span class="mf">5.4</span><span class="o">.</span><span class="mi">0</span>
+
+<span class="c1"># other config files may be included</span>
+<span class="nd">@linux</span><span class="o">.</span><span class="n">options</span>
+</pre></div>
+</div>
+<p>Files included by <cite>@file</cite> directives in configuration files are resolved
+relative to the including file. For example, if a configuration file
+<cite>~/.llvm/target.cfg</cite> contains the directive <cite>@os/linux.opts</cite>, the file
+<cite>linux.opts</cite> is searched for in the directory <cite>~/.llvm/os</cite>.</p>
+</div>
+</div>
+<div class="section" id="language-and-target-independent-features">
+<h2><a class="toc-backref" href="#id22">Language and Target-Independent Features</a><a class="headerlink" href="#language-and-target-independent-features" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="controlling-errors-and-warnings">
+<h3><a class="toc-backref" href="#id23">Controlling Errors and Warnings</a><a class="headerlink" href="#controlling-errors-and-warnings" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides a number of ways to control which code constructs cause
+it to emit errors and warning messages, and how they are displayed to
+the console.</p>
+<div class="section" id="controlling-how-clang-displays-diagnostics">
+<h4><a class="toc-backref" href="#id24">Controlling How Clang Displays Diagnostics</a><a class="headerlink" href="#controlling-how-clang-displays-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>When Clang emits a diagnostic, it includes rich information in the
+output, and gives you fine-grain control over which information is
+printed. Clang has the ability to print this information, and these are
+the options that control it:</p>
+<ol class="arabic simple">
+<li>A file/line/column indicator that shows exactly where the diagnostic
+occurs in your code [<a class="reference internal" href="#opt-fshow-column"><span class="std std-ref">-fshow-column</span></a>,
+<a class="reference internal" href="#opt-fshow-source-location"><span class="std std-ref">-fshow-source-location</span></a>].</li>
+<li>A categorization of the diagnostic as a note, warning, error, or
+fatal error.</li>
+<li>A text string that describes what the problem is.</li>
+<li>An option that indicates how to control the diagnostic (for
+diagnostics that support it)
+[<a class="reference internal" href="#opt-fdiagnostics-show-option"><span class="std std-ref">-fdiagnostics-show-option</span></a>].</li>
+<li>A <a class="reference internal" href="#diagnostics-categories"><span class="std std-ref">high-level category</span></a> for the diagnostic
+for clients that want to group diagnostics by class (for diagnostics
+that support it)
+[<a class="reference internal" href="#opt-fdiagnostics-show-category"><span class="std std-ref">-fdiagnostics-show-category</span></a>].</li>
+<li>The line of source code that the issue occurs on, along with a caret
+and ranges that indicate the important locations
+[<a class="reference internal" href="#opt-fcaret-diagnostics"><span class="std std-ref">-fcaret-diagnostics</span></a>].</li>
+<li>âFixItâ information, which is a concise explanation of how to fix the
+problem (when Clang is certain it knows)
+[<a class="reference internal" href="#opt-fdiagnostics-fixit-info"><span class="std std-ref">-fdiagnostics-fixit-info</span></a>].</li>
+<li>A machine-parsable representation of the ranges involved (off by
+default)
+[<a class="reference internal" href="#opt-fdiagnostics-print-source-range-info"><span class="std std-ref">-fdiagnostics-print-source-range-info</span></a>].</li>
+</ol>
+<p>For more information please see <a class="reference internal" href="#cl-diag-formatting"><span class="std std-ref">Formatting of
+Diagnostics</span></a>.</p>
+</div>
+<div class="section" id="diagnostic-mappings">
+<h4><a class="toc-backref" href="#id25">Diagnostic Mappings</a><a class="headerlink" href="#diagnostic-mappings" title="Permalink to this headline">¶</a></h4>
+<p>All diagnostics are mapped into one of these 6 classes:</p>
+<ul class="simple">
+<li>Ignored</li>
+<li>Note</li>
+<li>Remark</li>
+<li>Warning</li>
+<li>Error</li>
+<li>Fatal</li>
+</ul>
+</div>
+<div class="section" id="diagnostic-categories">
+<span id="diagnostics-categories"></span><h4><a class="toc-backref" href="#id26">Diagnostic Categories</a><a class="headerlink" href="#diagnostic-categories" title="Permalink to this headline">¶</a></h4>
+<p>Though not shown by default, diagnostics may each be associated with a
+high-level category. This category is intended to make it possible to
+triage builds that produce a large number of errors or warnings in a
+grouped way.</p>
+<p>Categories are not shown by default, but they can be turned on with the
+<a class="reference internal" href="#opt-fdiagnostics-show-category"><span class="std std-ref">-fdiagnostics-show-category</span></a> option.
+When set to â<code class="docutils literal notranslate"><span class="pre">name</span></code>â, the category is printed textually in the
+diagnostic output. When it is set to â<code class="docutils literal notranslate"><span class="pre">id</span></code>â, a category number is
+printed. The mapping of category names to category idâs can be obtained
+by running â<code class="docutils literal notranslate"><span class="pre">clang</span> <span class="pre">--print-diagnostic-categories</span></code>â.</p>
+</div>
+<div class="section" id="controlling-diagnostics-via-command-line-flags">
+<h4><a class="toc-backref" href="#id27">Controlling Diagnostics via Command Line Flags</a><a class="headerlink" href="#controlling-diagnostics-via-command-line-flags" title="Permalink to this headline">¶</a></h4>
+<p>TODO: -W flags, -pedantic, etc</p>
+</div>
+<div class="section" id="controlling-diagnostics-via-pragmas">
+<span id="pragma-gcc-diagnostic"></span><h4><a class="toc-backref" href="#id28">Controlling Diagnostics via Pragmas</a><a class="headerlink" href="#controlling-diagnostics-via-pragmas" title="Permalink to this headline">¶</a></h4>
+<p>Clang can also control what diagnostics are enabled through the use of
+pragmas in the source code. This is useful for turning off specific
+warnings in a section of source code. Clang supports GCCâs pragma for
+compatibility with existing source code, as well as several extensions.</p>
+<p>The pragma may control any warning that can be used from the command
+line. Warnings may be set to ignored, warning, error, or fatal. The
+following example code will tell Clang or GCC to ignore the -Wall
+warnings:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma GCC diagnostic ignored "-Wall"</span>
+</pre></div>
+</div>
+<p>In addition to all of the functionality provided by GCCâs pragma, Clang
+also allows you to push and pop the current warning state. This is
+particularly useful when writing a header file that will be compiled by
+other people, because you donât know what warning flags they build with.</p>
+<p>In the below example <a class="reference internal" href="#cmdoption-wextra-tokens"><code class="xref std std-option docutils literal notranslate"><span class="pre">-Wextra-tokens</span></code></a> is ignored for only a single line
+of code, after which the diagnostics return to whatever state had previously
+existed.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// warning: extra tokens at end of #endif directive</span>
+
+<span class="cp">#pragma clang diagnostic push</span>
+<span class="cp">#pragma clang diagnostic ignored "-Wextra-tokens"</span>
+
+<span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// no warning</span>
+
+<span class="cp">#pragma clang diagnostic pop</span>
+</pre></div>
+</div>
+<p>The push and pop pragmas will save and restore the full diagnostic state
+of the compiler, regardless of how it was set. That means that it is
+possible to use push and pop around GCC compatible diagnostics and Clang
+will push and pop them appropriately, while GCC will ignore the pushes
+and pops as unknown pragmas. It should be noted that while Clang
+supports the GCC pragma, Clang and GCC do not support the exact same set
+of warnings, so even when using GCC compatible #pragmas there is no
+guarantee that they will have identical behaviour on both compilers.</p>
+<p>In addition to controlling warnings and errors generated by the compiler, it is
+possible to generate custom warning and error messages through the following
+pragmas:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// The following will produce warning messages</span>
+<span class="cp">#pragma message "some diagnostic message"</span>
+<span class="cp">#pragma GCC warning "TODO: replace deprecated feature"</span>
+
+<span class="c1">// The following will produce an error message</span>
+<span class="cp">#pragma GCC error "Not supported"</span>
+</pre></div>
+</div>
+<p>These pragmas operate similarly to the <code class="docutils literal notranslate"><span class="pre">#warning</span></code> and <code class="docutils literal notranslate"><span class="pre">#error</span></code> preprocessor
+directives, except that they may also be embedded into preprocessor macros via
+the C99 <code class="docutils literal notranslate"><span class="pre">_Pragma</span></code> operator, for example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#define STR(X) #X</span>
+<span class="cp">#define DEFER(M,...) M(__VA_ARGS__)</span>
+<span class="cp">#define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))</span>
+
+<span class="n">CUSTOM_ERROR</span><span class="p">(</span><span class="s">"Feature not available"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="controlling-diagnostics-in-system-headers">
+<h4><a class="toc-backref" href="#id29">Controlling Diagnostics in System Headers</a><a class="headerlink" href="#controlling-diagnostics-in-system-headers" title="Permalink to this headline">¶</a></h4>
+<p>Warnings are suppressed when they occur in system headers. By default,
+an included file is treated as a system header if it is found in an
+include path specified by <code class="docutils literal notranslate"><span class="pre">-isystem</span></code>, but this can be overridden in
+several ways.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">system_header</span></code> pragma can be used to mark the current file as
+being a system header. No warnings will be produced from the location of
+the pragma onwards within the same file.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// warning: extra tokens at end of #endif directive</span>
+
+<span class="cp">#pragma clang system_header</span>
+
+<span class="cp">#if foo</span>
+<span class="cp">#endif foo </span><span class="c1">// no warning</span>
+</pre></div>
+</div>
+<p>The <cite>âsystem-header-prefix=</cite> and <cite>âno-system-header-prefix=</cite>
+command-line arguments can be used to override whether subsets of an include
+path are treated as system headers. When the name in a <code class="docutils literal notranslate"><span class="pre">#include</span></code> directive
+is found within a header search path and starts with a system prefix, the
+header is treated as a system header. The last prefix on the
+command-line which matches the specified header name takes precedence.
+For instance:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -Ifoo -isystem bar --system-header-prefix<span class="o">=</span>x/ <span class="se">\</span>
+ --no-system-header-prefix<span class="o">=</span>x/y/
+</pre></div>
+</div>
+<p>Here, <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"x/a.h"</span></code> is treated as including a system header, even
+if the header is found in <code class="docutils literal notranslate"><span class="pre">foo</span></code>, and <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"x/y/b.h"</span></code> is treated
+as not including a system header, even if the header is found in
+<code class="docutils literal notranslate"><span class="pre">bar</span></code>.</p>
+<p>A <code class="docutils literal notranslate"><span class="pre">#include</span></code> directive which finds a file relative to the current
+directory is treated as including a system header if the including file
+is treated as a system header.</p>
+</div>
+<div class="section" id="enabling-all-diagnostics">
+<span id="diagnostics-enable-everything"></span><h4><a class="toc-backref" href="#id30">Enabling All Diagnostics</a><a class="headerlink" href="#enabling-all-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>In addition to the traditional <code class="docutils literal notranslate"><span class="pre">-W</span></code> flags, one can enable <strong>all</strong>
+diagnostics by passing <a class="reference internal" href="#cmdoption-weverything"><code class="xref std std-option docutils literal notranslate"><span class="pre">-Weverything</span></code></a>. This works as expected
+with
+<a class="reference internal" href="#cmdoption-werror"><code class="xref std std-option docutils literal notranslate"><span class="pre">-Werror</span></code></a>, and also includes the warnings from <a class="reference internal" href="#cmdoption-pedantic"><code class="xref std std-option docutils literal notranslate"><span class="pre">-pedantic</span></code></a>.</p>
+<p>Note that when combined with <a class="reference internal" href="#cmdoption-w"><code class="xref std std-option docutils literal notranslate"><span class="pre">-w</span></code></a> (which disables all warnings), that
+flag wins.</p>
+</div>
+<div class="section" id="controlling-static-analyzer-diagnostics">
+<h4><a class="toc-backref" href="#id31">Controlling Static Analyzer Diagnostics</a><a class="headerlink" href="#controlling-static-analyzer-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>While not strictly part of the compiler, the diagnostics from Clangâs
+<a class="reference external" href="https://clang-analyzer.llvm.org">static analyzer</a> can also be
+influenced by the user via changes to the source code. See the available
+<a class="reference external" href="https://clang-analyzer.llvm.org/annotations.html">annotations</a> and the
+analyzerâs <a class="reference external" href="https://clang-analyzer.llvm.org/faq.html#exclude_code">FAQ
+page</a> for more
+information.</p>
+</div>
+</div>
+<div class="section" id="precompiled-headers">
+<span id="usersmanual-precompiled-headers"></span><h3><a class="toc-backref" href="#id32">Precompiled Headers</a><a class="headerlink" href="#precompiled-headers" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://en.wikipedia.org/wiki/Precompiled_header">Precompiled headers</a>
+are a general approach employed by many compilers to reduce compilation
+time. The underlying motivation of the approach is that it is common for
+the same (and often large) header files to be included by multiple
+source files. Consequently, compile times can often be greatly improved
+by caching some of the (redundant) work done by a compiler to process
+headers. Precompiled header files, which represent one of many ways to
+implement this optimization, are literally files that represent an
+on-disk cache that contains the vital information necessary to reduce
+some of the work needed to process a corresponding header file. While
+details of precompiled headers vary between compilers, precompiled
+headers have been shown to be highly effective at speeding up program
+compilation on systems with very large system headers (e.g., macOS).</p>
+<div class="section" id="generating-a-pch-file">
+<h4><a class="toc-backref" href="#id33">Generating a PCH File</a><a class="headerlink" href="#generating-a-pch-file" title="Permalink to this headline">¶</a></h4>
+<p>To generate a PCH file using Clang, one invokes Clang with the
+<cite>-x <language>-header</cite> option. This mirrors the interface in GCC
+for generating PCH files:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> gcc -x c-header test.h -o test.h.gch
+<span class="gp">$</span> clang -x c-header test.h -o test.h.pch
+</pre></div>
+</div>
+</div>
+<div class="section" id="using-a-pch-file">
+<h4><a class="toc-backref" href="#id34">Using a PCH File</a><a class="headerlink" href="#using-a-pch-file" title="Permalink to this headline">¶</a></h4>
+<p>A PCH file can then be used as a prefix header when a <a class="reference internal" href="CommandGuide/clang.html#cmdoption-include"><code class="xref std std-option docutils literal notranslate"><span class="pre">-include</span></code></a>
+option is passed to <code class="docutils literal notranslate"><span class="pre">clang</span></code>:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -include test.h test.c -o <span class="nb">test</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">clang</span></code> driver will first check if a PCH file for <code class="docutils literal notranslate"><span class="pre">test.h</span></code> is
+available; if so, the contents of <code class="docutils literal notranslate"><span class="pre">test.h</span></code> (and the files it includes)
+will be processed from the PCH file. Otherwise, Clang falls back to
+directly processing the content of <code class="docutils literal notranslate"><span class="pre">test.h</span></code>. This mirrors the behavior
+of GCC.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>Clang does <em>not</em> automatically use PCH files for headers that are directly
+included within a source file. For example:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -x c-header test.h -o test.h.pch
+<span class="gp">$</span> cat test.c
+<span class="gp">#</span>include <span class="s2">"test.h"</span>
+<span class="gp">$</span> clang test.c -o <span class="nb">test</span>
+</pre></div>
+</div>
+<p class="last">In this example, <code class="docutils literal notranslate"><span class="pre">clang</span></code> will not automatically use the PCH file for
+<code class="docutils literal notranslate"><span class="pre">test.h</span></code> since <code class="docutils literal notranslate"><span class="pre">test.h</span></code> was included directly in the source file and not
+specified on the command line using <a class="reference internal" href="CommandGuide/clang.html#cmdoption-include"><code class="xref std std-option docutils literal notranslate"><span class="pre">-include</span></code></a>.</p>
+</div>
+</div>
+<div class="section" id="relocatable-pch-files">
+<h4><a class="toc-backref" href="#id35">Relocatable PCH Files</a><a class="headerlink" href="#relocatable-pch-files" title="Permalink to this headline">¶</a></h4>
+<p>It is sometimes necessary to build a precompiled header from headers
+that are not yet in their final, installed locations. For example, one
+might build a precompiled header within the build tree that is then
+meant to be installed alongside the headers. Clang permits the creation
+of ârelocatableâ precompiled headers, which are built with a given path
+(into the build directory) and can later be used from an installed
+location.</p>
+<p>To build a relocatable precompiled header, place your headers into a
+subdirectory whose structure mimics the installed location. For example,
+if you want to build a precompiled header for the header <code class="docutils literal notranslate"><span class="pre">mylib.h</span></code>
+that will be installed into <code class="docutils literal notranslate"><span class="pre">/usr/include</span></code>, create a subdirectory
+<code class="docutils literal notranslate"><span class="pre">build/usr/include</span></code> and place the header <code class="docutils literal notranslate"><span class="pre">mylib.h</span></code> into that
+subdirectory. If <code class="docutils literal notranslate"><span class="pre">mylib.h</span></code> depends on other headers, then they can be
+stored within <code class="docutils literal notranslate"><span class="pre">build/usr/include</span></code> in a way that mimics the installed
+location.</p>
+<p>Building a relocatable precompiled header requires two additional
+arguments. First, pass the <code class="docutils literal notranslate"><span class="pre">--relocatable-pch</span></code> flag to indicate that
+the resulting PCH file should be relocatable. Second, pass
+<code class="docutils literal notranslate"><span class="pre">-isysroot</span> <span class="pre">/path/to/build</span></code>, which makes all includes for your library
+relative to the build directory. For example:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">#</span> clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+</pre></div>
+</div>
+<p>When loading the relocatable PCH file, the various headers used in the
+PCH file are found from the system header root. For example, <code class="docutils literal notranslate"><span class="pre">mylib.h</span></code>
+can be found in <code class="docutils literal notranslate"><span class="pre">/usr/include/mylib.h</span></code>. If the headers are installed
+in some other system root, the <code class="docutils literal notranslate"><span class="pre">-isysroot</span></code> option can be used provide
+a different system root from which the headers will be based. For
+example, <code class="docutils literal notranslate"><span class="pre">-isysroot</span> <span class="pre">/Developer/SDKs/MacOSX10.4u.sdk</span></code> will look for
+<code class="docutils literal notranslate"><span class="pre">mylib.h</span></code> in <code class="docutils literal notranslate"><span class="pre">/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h</span></code>.</p>
+<p>Relocatable precompiled headers are intended to be used in a limited
+number of cases where the compilation environment is tightly controlled
+and the precompiled header cannot be generated after headers have been
+installed.</p>
+</div>
+</div>
+<div class="section" id="controlling-code-generation">
+<span id="id3"></span><h3><a class="toc-backref" href="#id36">Controlling Code Generation</a><a class="headerlink" href="#controlling-code-generation" title="Permalink to this headline">¶</a></h3>
+<p>Clang provides a number of ways to control code generation. The options
+are listed below.</p>
+<dl class="docutils">
+<dt><strong>-f[no-]sanitize=check1,check2,â¦</strong></dt>
+<dd><p class="first">Turn on runtime checks for various forms of undefined or suspicious
+behavior.</p>
+<p>This option controls whether Clang adds runtime checks for various
+forms of undefined or suspicious behavior, and is disabled by
+default. If a check fails, a diagnostic message is produced at
+runtime explaining the problem. The main checks are:</p>
+<ul class="simple">
+<li><p id="opt-fsanitize-address"><code class="docutils literal notranslate"><span class="pre">-fsanitize=address</span></code>:
+<a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>, a memory error
+detector.</p>
+</li>
+<li><p id="opt-fsanitize-thread"><code class="docutils literal notranslate"><span class="pre">-fsanitize=thread</span></code>: <a class="reference internal" href="ThreadSanitizer.html"><span class="doc">ThreadSanitizer</span></a>, a data race detector.</p>
+</li>
+<li><p id="opt-fsanitize-memory"><code class="docutils literal notranslate"><span class="pre">-fsanitize=memory</span></code>: <a class="reference internal" href="MemorySanitizer.html"><span class="doc">MemorySanitizer</span></a>,
+a detector of uninitialized reads. Requires instrumentation of all
+program code.</p>
+</li>
+<li><p id="opt-fsanitize-undefined"><code class="docutils literal notranslate"><span class="pre">-fsanitize=undefined</span></code>: <a class="reference internal" href="UndefinedBehaviorSanitizer.html"><span class="doc">UndefinedBehaviorSanitizer</span></a>,
+a fast and compatible undefined behavior checker.</p>
+</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=dataflow</span></code>: <a class="reference internal" href="DataFlowSanitizer.html"><span class="doc">DataFlowSanitizer</span></a>, a general data
+flow analysis.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=cfi</span></code>: <a class="reference internal" href="ControlFlowIntegrity.html"><span class="doc">control flow integrity</span></a>
+checks. Requires <code class="docutils literal notranslate"><span class="pre">-flto</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre">-fsanitize=safe-stack</span></code>: <a class="reference internal" href="SafeStack.html"><span class="doc">safe stack</span></a>
+protection against stack-based memory corruption errors.</li>
+</ul>
+<p>There are more fine-grained checks available: see
+the <a class="reference internal" href="UndefinedBehaviorSanitizer.html#ubsan-checks"><span class="std std-ref">list</span></a> of specific kinds of
+undefined behavior that can be detected and the <a class="reference internal" href="ControlFlowIntegrity.html#cfi-schemes"><span class="std std-ref">list</span></a>
+of control flow integrity schemes.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">-fsanitize=</span></code> argument must also be provided when linking, in
+order to link to the appropriate runtime library.</p>
+<p class="last">It is not possible to combine more than one of the <code class="docutils literal notranslate"><span class="pre">-fsanitize=address</span></code>,
+<code class="docutils literal notranslate"><span class="pre">-fsanitize=thread</span></code>, and <code class="docutils literal notranslate"><span class="pre">-fsanitize=memory</span></code> checkers in the same
+program.</p>
+</dd>
+</dl>
+<p><strong>-f[no-]sanitize-recover=check1,check2,â¦</strong></p>
+<p><strong>-f[no-]sanitize-recover=all</strong></p>
+<blockquote>
+<div><p>Controls which checks enabled by <code class="docutils literal notranslate"><span class="pre">-fsanitize=</span></code> flag are non-fatal.
+If the check is fatal, program will halt after the first error
+of this kind is detected and error report is printed.</p>
+<p>By default, non-fatal checks are those enabled by
+<a class="reference internal" href="UndefinedBehaviorSanitizer.html"><span class="doc">UndefinedBehaviorSanitizer</span></a>,
+except for <code class="docutils literal notranslate"><span class="pre">-fsanitize=return</span></code> and <code class="docutils literal notranslate"><span class="pre">-fsanitize=unreachable</span></code>. Some
+sanitizers may not support recovery (or not support it by default
+e.g. <a class="reference internal" href="AddressSanitizer.html"><span class="doc">AddressSanitizer</span></a>), and always crash the program after the issue
+is detected.</p>
+<p>Note that the <code class="docutils literal notranslate"><span class="pre">-fsanitize-trap</span></code> flag has precedence over this flag.
+This means that if a check has been configured to trap elsewhere on the
+command line, or if the check traps by default, this flag will not have
+any effect unless that sanitizerâs trapping behavior is disabled with
+<code class="docutils literal notranslate"><span class="pre">-fno-sanitize-trap</span></code>.</p>
+<p>For example, if a command line contains the flags <code class="docutils literal notranslate"><span class="pre">-fsanitize=undefined</span>
+<span class="pre">-fsanitize-trap=undefined</span></code>, the flag <code class="docutils literal notranslate"><span class="pre">-fsanitize-recover=alignment</span></code>
+will have no effect on its own; it will need to be accompanied by
+<code class="docutils literal notranslate"><span class="pre">-fno-sanitize-trap=alignment</span></code>.</p>
+</div></blockquote>
+<p><strong>-f[no-]sanitize-trap=check1,check2,â¦</strong></p>
+<blockquote>
+<div><p>Controls which checks enabled by the <code class="docutils literal notranslate"><span class="pre">-fsanitize=</span></code> flag trap. This
+option is intended for use in cases where the sanitizer runtime cannot
+be used (for instance, when building libc or a kernel module), or where
+the binary size increase caused by the sanitizer runtime is a concern.</p>
+<p>This flag is only compatible with <a class="reference internal" href="ControlFlowIntegrity.html"><span class="doc">control flow integrity</span></a> schemes and <a class="reference internal" href="UndefinedBehaviorSanitizer.html"><span class="doc">UndefinedBehaviorSanitizer</span></a>
+checks other than <code class="docutils literal notranslate"><span class="pre">vptr</span></code>. If this flag
+is supplied together with <code class="docutils literal notranslate"><span class="pre">-fsanitize=undefined</span></code>, the <code class="docutils literal notranslate"><span class="pre">vptr</span></code> sanitizer
+will be implicitly disabled.</p>
+<p>This flag is enabled by default for sanitizers in the <code class="docutils literal notranslate"><span class="pre">cfi</span></code> group.</p>
+</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-blacklist">
+<code class="descname">-fsanitize-blacklist</code><code class="descclassname">=/path/to/blacklist/file</code><a class="headerlink" href="#cmdoption-fsanitize-blacklist" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable or modify sanitizer checks for objects (source files, functions,
+variables, types) listed in the file. See
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><span class="doc">Sanitizer special case list</span></a> for file format description.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-sanitize-blacklist">
+<code class="descname">-fno-sanitize-blacklist</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fno-sanitize-blacklist" title="Permalink to this definition">¶</a></dt>
+<dd><p>Donât use blacklist file, if it was specified earlier in the command line.</p>
+</dd></dl>
+
+<p><strong>-f[no-]sanitize-coverage=[type,features,â¦]</strong></p>
+<blockquote>
+<div>Enable simple code coverage in addition to certain sanitizers.
+See <a class="reference internal" href="SanitizerCoverage.html"><span class="doc">SanitizerCoverage</span></a> for more details.</div></blockquote>
+<p><strong>-f[no-]sanitize-stats</strong></p>
+<blockquote>
+<div>Enable simple statistics gathering for the enabled sanitizers.
+See <a class="reference internal" href="SanitizerStats.html"><span class="doc">SanitizerStats</span></a> for more details.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-undefined-trap-on-error">
+<code class="descname">-fsanitize-undefined-trap-on-error</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fsanitize-undefined-trap-on-error" title="Permalink to this definition">¶</a></dt>
+<dd><p>Deprecated alias for <code class="docutils literal notranslate"><span class="pre">-fsanitize-trap=undefined</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fsanitize-cfi-cross-dso">
+<code class="descname">-fsanitize-cfi-cross-dso</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fsanitize-cfi-cross-dso" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable cross-DSO control flow integrity checks. This flag modifies
+the behavior of sanitizers in the <code class="docutils literal notranslate"><span class="pre">cfi</span></code> group to allow checking
+of cross-DSO virtual and indirect calls.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fsanitize-cfi-icall-generalize-pointers">
+<code class="descname">-fsanitize-cfi-icall-generalize-pointers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fsanitize-cfi-icall-generalize-pointers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generalize pointers in return and argument types in function type signatures
+checked by Control Flow Integrity indirect call checking. See
+<a class="reference internal" href="ControlFlowIntegrity.html"><span class="doc">Control Flow Integrity</span></a> for more details.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fstrict-vtable-pointers">
+<code class="descname">-fstrict-vtable-pointers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fstrict-vtable-pointers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable optimizations based on the strict rules for overwriting polymorphic
+C++ objects, i.e. the vptr is invariant during an objectâs lifetime.
+This enables better devirtualization. Turned off by default, because it is
+still experimental.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ffast-math">
+<code class="descname">-ffast-math</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-ffast-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable fast-math mode. This defines the <code class="docutils literal notranslate"><span class="pre">__FAST_MATH__</span></code> preprocessor
+macro, and lets the compiler make aggressive, potentially-lossy assumptions
+about floating-point math. These include:</p>
+<ul class="simple">
+<li>Floating-point math obeys regular algebraic rules for real numbers (e.g.
+<code class="docutils literal notranslate"><span class="pre">+</span></code> and <code class="docutils literal notranslate"><span class="pre">*</span></code> are associative, <code class="docutils literal notranslate"><span class="pre">x/y</span> <span class="pre">==</span> <span class="pre">x</span> <span class="pre">*</span> <span class="pre">(1/y)</span></code>, and
+<code class="docutils literal notranslate"><span class="pre">(a</span> <span class="pre">+</span> <span class="pre">b)</span> <span class="pre">*</span> <span class="pre">c</span> <span class="pre">==</span> <span class="pre">a</span> <span class="pre">*</span> <span class="pre">c</span> <span class="pre">+</span> <span class="pre">b</span> <span class="pre">*</span> <span class="pre">c</span></code>),</li>
+<li>operands to floating-point operations are not equal to <code class="docutils literal notranslate"><span class="pre">NaN</span></code> and
+<code class="docutils literal notranslate"><span class="pre">Inf</span></code>, and</li>
+<li><code class="docutils literal notranslate"><span class="pre">+0</span></code> and <code class="docutils literal notranslate"><span class="pre">-0</span></code> are interchangeable.</li>
+</ul>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fdenormal-fp-math">
+<code class="descname">-fdenormal-fp-math</code><code class="descclassname">=[values]</code><a class="headerlink" href="#cmdoption-fdenormal-fp-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select which denormal numbers the code is permitted to require.</p>
+<p>Valid values are: <code class="docutils literal notranslate"><span class="pre">ieee</span></code>, <code class="docutils literal notranslate"><span class="pre">preserve-sign</span></code>, and <code class="docutils literal notranslate"><span class="pre">positive-zero</span></code>,
+which correspond to IEEE 754 denormal numbers, the sign of a
+flushed-to-zero number is preserved in the sign of 0, denormals are
+flushed to positive zero, respectively.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-f-no-strict-float-cast-overflow">
+<code class="descname">-f[no-]strict-float-cast-overflow</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-f-no-strict-float-cast-overflow" title="Permalink to this definition">¶</a></dt>
+<dd><p>When a floating-point value is not representable in a destination integer
+type, the code has undefined behavior according to the language standard.
+By default, Clang will not guarantee any particular result in that case.
+With the âno-strictâ option, Clang attempts to match the overflowing behavior
+of the targetâs native float-to-int conversion instructions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fwhole-program-vtables">
+<code class="descname">-fwhole-program-vtables</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fwhole-program-vtables" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable whole-program vtable optimizations, such as single-implementation
+devirtualization and virtual constant propagation, for classes with
+<a class="reference internal" href="LTOVisibility.html"><span class="doc">hidden LTO visibility</span></a>. Requires <code class="docutils literal notranslate"><span class="pre">-flto</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fforce-emit-vtables">
+<code class="descname">-fforce-emit-vtables</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fforce-emit-vtables" title="Permalink to this definition">¶</a></dt>
+<dd><p>In order to improve devirtualization, forces emitting of vtables even in
+modules where it isnât necessary. It causes more inline virtual functions
+to be emitted.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-assume-sane-operator-new">
+<code class="descname">-fno-assume-sane-operator-new</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fno-assume-sane-operator-new" title="Permalink to this definition">¶</a></dt>
+<dd><p>Donât assume that the C++âs new operator is sane.</p>
+<p>This option tells the compiler to do not assume that C++âs global
+new operator will always return a pointer that does not alias any
+other pointer when the function returns.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftrap-function">
+<code class="descname">-ftrap-function</code><code class="descclassname">=[name]</code><a class="headerlink" href="#cmdoption-ftrap-function" title="Permalink to this definition">¶</a></dt>
+<dd><p>Instruct code generator to emit a function call to the specified
+function name for <code class="docutils literal notranslate"><span class="pre">__builtin_trap()</span></code>.</p>
+<p>LLVM code generator translates <code class="docutils literal notranslate"><span class="pre">__builtin_trap()</span></code> to a trap
+instruction if it is supported by the target ISA. Otherwise, the
+builtin is translated into a call to <code class="docutils literal notranslate"><span class="pre">abort</span></code>. If this option is
+set, then the code generator will always lower the builtin to a call
+to the specified function regardless of whether the target ISA has a
+trap instruction. This option is useful for environments (e.g.
+deeply embedded) where a trap cannot be properly handled, or when
+some custom behavior is desired.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftls-model">
+<code class="descname">-ftls-model</code><code class="descclassname">=[model]</code><a class="headerlink" href="#cmdoption-ftls-model" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select which TLS model to use.</p>
+<p>Valid values are: <code class="docutils literal notranslate"><span class="pre">global-dynamic</span></code>, <code class="docutils literal notranslate"><span class="pre">local-dynamic</span></code>,
+<code class="docutils literal notranslate"><span class="pre">initial-exec</span></code> and <code class="docutils literal notranslate"><span class="pre">local-exec</span></code>. The default value is
+<code class="docutils literal notranslate"><span class="pre">global-dynamic</span></code>. The compiler may use a different model if the
+selected model is not supported by the target, or if a more
+efficient model can be used. The TLS model can be overridden per
+variable using the <code class="docutils literal notranslate"><span class="pre">tls_model</span></code> attribute.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-femulated-tls">
+<code class="descname">-femulated-tls</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-femulated-tls" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select emulated TLS model, which overrides all -ftls-model choices.</p>
+<p>In emulated TLS mode, all access to TLS variables are converted to
+calls to __emutls_get_address in the runtime library.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mhwdiv">
+<code class="descname">-mhwdiv</code><code class="descclassname">=[values]</code><a class="headerlink" href="#cmdoption-mhwdiv" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select the ARM modes (arm or thumb) that support hardware division
+instructions.</p>
+<p>Valid values are: <code class="docutils literal notranslate"><span class="pre">arm</span></code>, <code class="docutils literal notranslate"><span class="pre">thumb</span></code> and <code class="docutils literal notranslate"><span class="pre">arm,thumb</span></code>.
+This option is used to indicate which mode (arm or thumb) supports
+hardware division instructions. This only applies to the ARM
+architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-m-no-crc">
+<code class="descname">-m[no-]crc</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-m-no-crc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable or disable CRC instructions.</p>
+<p>This option is used to indicate whether CRC instructions are to
+be generated. This only applies to the ARM architecture.</p>
+<p>CRC instructions are enabled by default on ARMv8.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mgeneral-regs-only">
+<code class="descname">-mgeneral-regs-only</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-mgeneral-regs-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate code which only uses the general purpose registers.</p>
+<p>This option restricts the generated code to use general registers
+only. This only applies to the AArch64 architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mcompact-branches">
+<code class="descname">-mcompact-branches</code><code class="descclassname">=[values]</code><a class="headerlink" href="#cmdoption-mcompact-branches" title="Permalink to this definition">¶</a></dt>
+<dd><p>Control the usage of compact branches for MIPSR6.</p>
+<p>Valid values are: <code class="docutils literal notranslate"><span class="pre">never</span></code>, <code class="docutils literal notranslate"><span class="pre">optimal</span></code> and <code class="docutils literal notranslate"><span class="pre">always</span></code>.
+The default value is <code class="docutils literal notranslate"><span class="pre">optimal</span></code> which generates compact branches
+when a delay slot cannot be filled. <code class="docutils literal notranslate"><span class="pre">never</span></code> disables the usage of
+compact branches and <code class="docutils literal notranslate"><span class="pre">always</span></code> generates compact branches whenever
+possible.</p>
+</dd></dl>
+
+<dl class="docutils">
+<dt><strong>-f[no-]max-type-align=[number]</strong></dt>
+<dd><p class="first">Instruct the code generator to not enforce a higher alignment than the given
+number (of bytes) when accessing memory via an opaque pointer or reference.
+This cap is ignored when directly accessing a variable or when the pointee
+type has an explicit âalignedâ attribute.</p>
+<p>The value should usually be determined by the properties of the system allocator.
+Some builtin types, especially vector types, have very high natural alignments;
+when working with values of those types, Clang usually wants to use instructions
+that take advantage of that alignment. However, many system allocators do
+not promise to return memory that is more than 8-byte or 16-byte-aligned. Use
+this option to limit the alignment that the compiler can assume for an arbitrary
+pointer, which may point onto the heap.</p>
+<p>This option does not affect the ABI alignment of types; the layout of structs and
+unions and the value returned by the alignof operator remain the same.</p>
+<p>This option can be overridden on a case-by-case basis by putting an explicit
+âalignedâ alignment on a struct, union, or typedef. For example:</p>
+<div class="last highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">#</span>include <immintrin.h>
+<span class="go">// Make an aligned typedef of the AVX-512 16-int vector type.</span>
+<span class="go">typedef __v16si __aligned_v16si __attribute__((aligned(64)));</span>
+
+<span class="go">void initialize_vector(__aligned_v16si *v) {</span>
+<span class="go"> // The compiler may assume that âvâ is 64-byte aligned, regardless of the</span>
+<span class="go"> // value of -fmax-type-align.</span>
+<span class="go">}</span>
+</pre></div>
+</div>
+</dd>
+</dl>
+<dl class="option">
+<dt id="cmdoption-faddrsig">
+<code class="descname">-faddrsig</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-fno-addrsig</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-faddrsig" title="Permalink to this definition">¶</a></dt>
+<dd><p>Controls whether Clang emits an address-significance table into the object
+file. Address-significance tables allow linkers to implement <a class="reference external" href="https://research.google.com/pubs/archive/36912.pdf">safe ICF</a> without the false
+positives that can result from other implementation techniques such as
+relocation scanning. Address-significance tables are enabled by default
+on ELF targets when using the integrated assembler. This flag currently
+only has an effect on ELF targets.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="profile-guided-optimization">
+<h3><a class="toc-backref" href="#id37">Profile Guided Optimization</a><a class="headerlink" href="#profile-guided-optimization" title="Permalink to this headline">¶</a></h3>
+<p>Profile information enables better optimization. For example, knowing that a
+branch is taken very frequently helps the compiler make better decisions when
+ordering basic blocks. Knowing that a function <code class="docutils literal notranslate"><span class="pre">foo</span></code> is called more
+frequently than another function <code class="docutils literal notranslate"><span class="pre">bar</span></code> helps the inliner. Optimization
+levels <code class="docutils literal notranslate"><span class="pre">-O2</span></code> and above are recommended for use of profile guided optimization.</p>
+<p>Clang supports profile guided optimization with two different kinds of
+profiling. A sampling profiler can generate a profile with very low runtime
+overhead, or you can build an instrumented version of the code that collects
+more detailed profile information. Both kinds of profiles can provide execution
+counts for instructions in the code and information on branches taken and
+function invocation.</p>
+<p>Regardless of which kind of profiling you use, be careful to collect profiles
+by running your code with inputs that are representative of the typical
+behavior. Code that is not exercised in the profile will be optimized as if it
+is unimportant, and the compiler may make poor optimization choices for code
+that is disproportionately used while profiling.</p>
+<div class="section" id="differences-between-sampling-and-instrumentation">
+<h4><a class="toc-backref" href="#id38">Differences Between Sampling and Instrumentation</a><a class="headerlink" href="#differences-between-sampling-and-instrumentation" title="Permalink to this headline">¶</a></h4>
+<p>Although both techniques are used for similar purposes, there are important
+differences between the two:</p>
+<ol class="arabic simple">
+<li>Profile data generated with one cannot be used by the other, and there is no
+conversion tool that can convert one to the other. So, a profile generated
+via <code class="docutils literal notranslate"><span class="pre">-fprofile-instr-generate</span></code> must be used with <code class="docutils literal notranslate"><span class="pre">-fprofile-instr-use</span></code>.
+Similarly, sampling profiles generated by external profilers must be
+converted and used with <code class="docutils literal notranslate"><span class="pre">-fprofile-sample-use</span></code>.</li>
+<li>Instrumentation profile data can be used for code coverage analysis and
+optimization.</li>
+<li>Sampling profiles can only be used for optimization. They cannot be used for
+code coverage analysis. Although it would be technically possible to use
+sampling profiles for code coverage, sample-based profiles are too
+coarse-grained for code coverage purposes; it would yield poor results.</li>
+<li>Sampling profiles must be generated by an external tool. The profile
+generated by that tool must then be converted into a format that can be read
+by LLVM. The section on sampling profilers describes one of the supported
+sampling profile formats.</li>
+</ol>
+</div>
+<div class="section" id="using-sampling-profilers">
+<h4><a class="toc-backref" href="#id39">Using Sampling Profilers</a><a class="headerlink" href="#using-sampling-profilers" title="Permalink to this headline">¶</a></h4>
+<p>Sampling profilers are used to collect runtime information, such as
+hardware counters, while your application executes. They are typically
+very efficient and do not incur a large runtime overhead. The
+sample data collected by the profiler can be used during compilation
+to determine what the most executed areas of the code are.</p>
+<p>Using the data from a sample profiler requires some changes in the way
+a program is built. Before the compiler can use profiling information,
+the code needs to execute under the profiler. The following is the
+usual build cycle when using sample profilers for optimization:</p>
+<ol class="arabic">
+<li><p class="first">Build the code with source line table information. You can use all the
+usual build flags that you always build your application with. The only
+requirement is that you add <code class="docutils literal notranslate"><span class="pre">-gline-tables-only</span></code> or <code class="docutils literal notranslate"><span class="pre">-g</span></code> to the
+command line. This is important for the profiler to be able to map
+instructions back to source line locations.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang++ -O2 -gline-tables-only code.cc -o code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the executable under a sampling profiler. The specific profiler
+you use does not really matter, as long as its output can be converted
+into the format that the LLVM optimizer understands. Currently, there
+exists a conversion tool for the Linux Perf profiler
+(<a class="reference external" href="https://perf.wiki.kernel.org/">https://perf.wiki.kernel.org/</a>), so these examples assume that you
+are using Linux Perf to profile your code.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> perf record -b ./code
+</pre></div>
+</div>
+<p>Note the use of the <code class="docutils literal notranslate"><span class="pre">-b</span></code> flag. This tells Perf to use the Last Branch
+Record (LBR) to record call chains. While this is not strictly required,
+it provides better call information, which improves the accuracy of
+the profile data.</p>
+</li>
+<li><p class="first">Convert the collected profile data to LLVMâs sample profile format.
+This is currently supported via the AutoFDO converter <code class="docutils literal notranslate"><span class="pre">create_llvm_prof</span></code>.
+It is available at <a class="reference external" href="https://github.com/google/autofdo">https://github.com/google/autofdo</a>. Once built and
+installed, you can convert the <code class="docutils literal notranslate"><span class="pre">perf.data</span></code> file to LLVM using
+the command:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> create_llvm_prof --binary<span class="o">=</span>./code --out<span class="o">=</span>code.prof
+</pre></div>
+</div>
+<p>This will read <code class="docutils literal notranslate"><span class="pre">perf.data</span></code> and the binary file <code class="docutils literal notranslate"><span class="pre">./code</span></code> and emit
+the profile data in <code class="docutils literal notranslate"><span class="pre">code.prof</span></code>. Note that if you ran <code class="docutils literal notranslate"><span class="pre">perf</span></code>
+without the <code class="docutils literal notranslate"><span class="pre">-b</span></code> flag, you need to use <code class="docutils literal notranslate"><span class="pre">--use_lbr=false</span></code> when
+calling <code class="docutils literal notranslate"><span class="pre">create_llvm_prof</span></code>.</p>
+</li>
+<li><p class="first">Build the code again using the collected profile. This step feeds
+the profile back to the optimizers. This should result in a binary
+that executes faster than the original one. Note that you are not
+required to build the code with the exact same arguments that you
+used in the first step. The only requirement is that you build the code
+with <code class="docutils literal notranslate"><span class="pre">-gline-tables-only</span></code> and <code class="docutils literal notranslate"><span class="pre">-fprofile-sample-use</span></code>.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang++ -O2 -gline-tables-only -fprofile-sample-use<span class="o">=</span>code.prof code.cc -o code
+</pre></div>
+</div>
+</li>
+</ol>
+<div class="section" id="sample-profile-formats">
+<h5><a class="toc-backref" href="#id40">Sample Profile Formats</a><a class="headerlink" href="#sample-profile-formats" title="Permalink to this headline">¶</a></h5>
+<p>Since external profilers generate profile data in a variety of custom formats,
+the data generated by the profiler must be converted into a format that can be
+read by the backend. LLVM supports three different sample profile formats:</p>
+<ol class="arabic simple">
+<li>ASCII text. This is the easiest one to generate. The file is divided into
+sections, which correspond to each of the functions with profile
+information. The format is described below. It can also be generated from
+the binary or gcov formats using the <code class="docutils literal notranslate"><span class="pre">llvm-profdata</span></code> tool.</li>
+<li>Binary encoding. This uses a more efficient encoding that yields smaller
+profile files. This is the format generated by the <code class="docutils literal notranslate"><span class="pre">create_llvm_prof</span></code> tool
+in <a class="reference external" href="https://github.com/google/autofdo">https://github.com/google/autofdo</a>.</li>
+<li>GCC encoding. This is based on the gcov format, which is accepted by GCC. It
+is only interesting in environments where GCC and Clang co-exist. This
+encoding is only generated by the <code class="docutils literal notranslate"><span class="pre">create_gcov</span></code> tool in
+<a class="reference external" href="https://github.com/google/autofdo">https://github.com/google/autofdo</a>. It can be read by LLVM and
+<code class="docutils literal notranslate"><span class="pre">llvm-profdata</span></code>, but it cannot be generated by either.</li>
+</ol>
+<p>If you are using Linux Perf to generate sampling profiles, you can use the
+conversion tool <code class="docutils literal notranslate"><span class="pre">create_llvm_prof</span></code> described in the previous section.
+Otherwise, you will need to write a conversion tool that converts your
+profilerâs native format into one of these three.</p>
+</div>
+<div class="section" id="sample-profile-text-format">
+<h5><a class="toc-backref" href="#id41">Sample Profile Text Format</a><a class="headerlink" href="#sample-profile-text-format" title="Permalink to this headline">¶</a></h5>
+<p>This section describes the ASCII text format for sampling profiles. It is,
+arguably, the easiest one to generate. If you are interested in generating any
+of the other two, consult the <code class="docutils literal notranslate"><span class="pre">ProfileData</span></code> library in LLVMâs source tree
+(specifically, <code class="docutils literal notranslate"><span class="pre">include/llvm/ProfileData/SampleProfReader.h</span></code>).</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">function1:total_samples:total_head_samples</span>
+<span class="go"> offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]</span>
+<span class="go"> offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]</span>
+<span class="go"> ...</span>
+<span class="go"> offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]</span>
+<span class="go"> offsetA[.discriminator]: fnA:num_of_total_samples</span>
+<span class="go"> offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]</span>
+<span class="go"> offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]</span>
+<span class="go"> offsetB[.discriminator]: fnB:num_of_total_samples</span>
+<span class="go"> offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]</span>
+</pre></div>
+</div>
+<p>This is a nested tree in which the indentation represents the nesting level
+of the inline stack. There are no blank lines in the file. And the spacing
+within a single line is fixed. Additional spaces will result in an error
+while reading the file.</p>
+<p>Any line starting with the â#â character is completely ignored.</p>
+<p>Inlined calls are represented with indentation. The Inline stack is a
+stack of source locations in which the top of the stack represents the
+leaf function, and the bottom of the stack represents the actual
+symbol to which the instruction belongs.</p>
+<p>Function names must be mangled in order for the profile loader to
+match them in the current translation unit. The two numbers in the
+function header specify how many total samples were accumulated in the
+function (first number), and the total number of samples accumulated
+in the prologue of the function (second number). This head sample
+count provides an indicator of how frequently the function is invoked.</p>
+<p>There are two types of lines in the function body.</p>
+<ul class="simple">
+<li>Sampled line represents the profile information of a source location.
+<code class="docutils literal notranslate"><span class="pre">offsetN[.discriminator]:</span> <span class="pre">number_of_samples</span> <span class="pre">[fn5:num</span> <span class="pre">fn6:num</span> <span class="pre">...</span> <span class="pre">]</span></code></li>
+<li>Callsite line represents the profile information of an inlined callsite.
+<code class="docutils literal notranslate"><span class="pre">offsetA[.discriminator]:</span> <span class="pre">fnA:num_of_total_samples</span></code></li>
+</ul>
+<p>Each sampled line may contain several items. Some are optional (marked
+below):</p>
+<ol class="loweralpha">
+<li><p class="first">Source line offset. This number represents the line number
+in the function where the sample was collected. The line number is
+always relative to the line where symbol of the function is
+defined. So, if the function has its header at line 280, the offset
+13 is at line 293 in the file.</p>
+<p>Note that this offset should never be a negative number. This could
+happen in cases like macros. The debug machinery will register the
+line number at the point of macro expansion. So, if the macro was
+expanded in a line before the start of the function, the profile
+converter should emit a 0 as the offset (this means that the optimizers
+will not be able to associate a meaningful weight to the instructions
+in the macro).</p>
+</li>
+<li><p class="first">[OPTIONAL] Discriminator. This is used if the sampled program
+was compiled with DWARF discriminator support
+(<a class="reference external" href="http://wiki.dwarfstd.org/index.php?title=Path_Discriminators">http://wiki.dwarfstd.org/index.php?title=Path_Discriminators</a>).
+DWARF discriminators are unsigned integer values that allow the
+compiler to distinguish between multiple execution paths on the
+same source line location.</p>
+<p>For example, consider the line of code <code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">(cond)</span> <span class="pre">foo();</span> <span class="pre">else</span> <span class="pre">bar();</span></code>.
+If the predicate <code class="docutils literal notranslate"><span class="pre">cond</span></code> is true 80% of the time, then the edge
+into function <code class="docutils literal notranslate"><span class="pre">foo</span></code> should be considered to be taken most of the
+time. But both calls to <code class="docutils literal notranslate"><span class="pre">foo</span></code> and <code class="docutils literal notranslate"><span class="pre">bar</span></code> are at the same source
+line, so a sample count at that line is not sufficient. The
+compiler needs to know which part of that line is taken more
+frequently.</p>
+<p>This is what discriminators provide. In this case, the calls to
+<code class="docutils literal notranslate"><span class="pre">foo</span></code> and <code class="docutils literal notranslate"><span class="pre">bar</span></code> will be at the same line, but will have
+different discriminator values. This allows the compiler to correctly
+set edge weights into <code class="docutils literal notranslate"><span class="pre">foo</span></code> and <code class="docutils literal notranslate"><span class="pre">bar</span></code>.</p>
+</li>
+<li><p class="first">Number of samples. This is an integer quantity representing the
+number of samples collected by the profiler at this source
+location.</p>
+</li>
+<li><p class="first">[OPTIONAL] Potential call targets and samples. If present, this
+line contains a call instruction. This models both direct and
+number of samples. For example,</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">130: 7 foo:3 bar:2 baz:7</span>
+</pre></div>
+</div>
+<p>The above means that at relative line offset 130 there is a call
+instruction that calls one of <code class="docutils literal notranslate"><span class="pre">foo()</span></code>, <code class="docutils literal notranslate"><span class="pre">bar()</span></code> and <code class="docutils literal notranslate"><span class="pre">baz()</span></code>,
+with <code class="docutils literal notranslate"><span class="pre">baz()</span></code> being the relatively more frequently called target.</p>
+</li>
+</ol>
+<p>As an example, consider a program with the call chain <code class="docutils literal notranslate"><span class="pre">main</span> <span class="pre">-></span> <span class="pre">foo</span> <span class="pre">-></span> <span class="pre">bar</span></code>.
+When built with optimizations enabled, the compiler may inline the
+calls to <code class="docutils literal notranslate"><span class="pre">bar</span></code> and <code class="docutils literal notranslate"><span class="pre">foo</span></code> inside <code class="docutils literal notranslate"><span class="pre">main</span></code>. The generated profile
+could then be something like this:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">main:35504:0</span>
+<span class="go">1: _Z3foov:35504</span>
+<span class="go"> 2: _Z32bari:31977</span>
+<span class="go"> 1.1: 31977</span>
+<span class="go">2: 0</span>
+</pre></div>
+</div>
+<p>This profile indicates that there were a total of 35,504 samples
+collected in main. All of those were at line 1 (the call to <code class="docutils literal notranslate"><span class="pre">foo</span></code>).
+Of those, 31,977 were spent inside the body of <code class="docutils literal notranslate"><span class="pre">bar</span></code>. The last line
+of the profile (<code class="docutils literal notranslate"><span class="pre">2:</span> <span class="pre">0</span></code>) corresponds to line 2 inside <code class="docutils literal notranslate"><span class="pre">main</span></code>. No
+samples were collected there.</p>
+</div>
+</div>
+<div class="section" id="profiling-with-instrumentation">
+<h4><a class="toc-backref" href="#id42">Profiling with Instrumentation</a><a class="headerlink" href="#profiling-with-instrumentation" title="Permalink to this headline">¶</a></h4>
+<p>Clang also supports profiling via instrumentation. This requires building a
+special instrumented version of the code and has some runtime
+overhead during the profiling, but it provides more detailed results than a
+sampling profiler. It also provides reproducible results, at least to the
+extent that the code behaves consistently across runs.</p>
+<p>Here are the steps for using profile guided optimization with
+instrumentation:</p>
+<ol class="arabic">
+<li><p class="first">Build an instrumented version of the code by compiling and linking with the
+<code class="docutils literal notranslate"><span class="pre">-fprofile-instr-generate</span></code> option.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang++ -O2 -fprofile-instr-generate code.cc -o code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Run the instrumented executable with inputs that reflect the typical usage.
+By default, the profile data will be written to a <code class="docutils literal notranslate"><span class="pre">default.profraw</span></code> file
+in the current directory. You can override that default by using option
+<code class="docutils literal notranslate"><span class="pre">-fprofile-instr-generate=</span></code> or by setting the <code class="docutils literal notranslate"><span class="pre">LLVM_PROFILE_FILE</span></code>
+environment variable to specify an alternate file. If non-default file name
+is specified by both the environment variable and the command line option,
+the environment variable takes precedence. The file name pattern specified
+can include different modifiers: <code class="docutils literal notranslate"><span class="pre">%p</span></code>, <code class="docutils literal notranslate"><span class="pre">%h</span></code>, and <code class="docutils literal notranslate"><span class="pre">%m</span></code>.</p>
+<p>Any instance of <code class="docutils literal notranslate"><span class="pre">%p</span></code> in that file name will be replaced by the process
+ID, so that you can easily distinguish the profile output from multiple
+runs.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span><span class="s2">"code-%p.profraw"</span> ./code
+</pre></div>
+</div>
+<p>The modifier <code class="docutils literal notranslate"><span class="pre">%h</span></code> can be used in scenarios where the same instrumented
+binary is run in multiple different host machines dumping profile data
+to a shared network based storage. The <code class="docutils literal notranslate"><span class="pre">%h</span></code> specifier will be substituted
+with the hostname so that profiles collected from different hosts do not
+clobber each other.</p>
+<p>While the use of <code class="docutils literal notranslate"><span class="pre">%p</span></code> specifier can reduce the likelihood for the profiles
+dumped from different processes to clobber each other, such clobbering can still
+happen because of the <code class="docutils literal notranslate"><span class="pre">pid</span></code> re-use by the OS. Another side-effect of using
+<code class="docutils literal notranslate"><span class="pre">%p</span></code> is that the storage requirement for raw profile data files is greatly
+increased. To avoid issues like this, the <code class="docutils literal notranslate"><span class="pre">%m</span></code> specifier can used in the profile
+name. When this specifier is used, the profiler runtime will substitute <code class="docutils literal notranslate"><span class="pre">%m</span></code>
+with a unique integer identifier associated with the instrumented binary. Additionally,
+multiple raw profiles dumped from different processes that share a file system (can be
+on different hosts) will be automatically merged by the profiler runtime during the
+dumping. If the program links in multiple instrumented shared libraries, each library
+will dump the profile data into its own profile data file (with its unique integer
+id embedded in the profile name). Note that the merging enabled by <code class="docutils literal notranslate"><span class="pre">%m</span></code> is for raw
+profile data generated by profiler runtime. The resulting merged ârawâ profile data
+file still needs to be converted to a different format expected by the compiler (
+see step 3 below).</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span><span class="s2">"code-%m.profraw"</span> ./code
+</pre></div>
+</div>
+</li>
+<li><p class="first">Combine profiles from multiple runs and convert the ârawâ profile format to
+the input expected by clang. Use the <code class="docutils literal notranslate"><span class="pre">merge</span></code> command of the
+<code class="docutils literal notranslate"><span class="pre">llvm-profdata</span></code> tool to do this.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-profdata merge -output<span class="o">=</span>code.profdata code-*.profraw
+</pre></div>
+</div>
+<p>Note that this step is necessary even when there is only one ârawâ profile,
+since the merge operation also changes the file format.</p>
+</li>
+<li><p class="first">Build the code again using the <code class="docutils literal notranslate"><span class="pre">-fprofile-instr-use</span></code> option to specify the
+collected profile data.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang++ -O2 -fprofile-instr-use<span class="o">=</span>code.profdata code.cc -o code
+</pre></div>
+</div>
+<p>You can repeat step 4 as often as you like without regenerating the
+profile. As you make changes to your code, clang may no longer be able to
+use the profile data. It will warn you when this happens.</p>
+</li>
+</ol>
+<p>Profile generation using an alternative instrumentation method can be
+controlled by the GCC-compatible flags <code class="docutils literal notranslate"><span class="pre">-fprofile-generate</span></code> and
+<code class="docutils literal notranslate"><span class="pre">-fprofile-use</span></code>. Although these flags are semantically equivalent to
+their GCC counterparts, they <em>do not</em> handle GCC-compatible profiles.
+They are only meant to implement GCCâs semantics with respect to
+profile creation and use. Flag <code class="docutils literal notranslate"><span class="pre">-fcs-profile-generate</span></code> also instruments
+programs using the same instrumentation method as <code class="docutils literal notranslate"><span class="pre">-fprofile-generate</span></code>.</p>
+<dl class="option">
+<dt id="cmdoption-fprofile-generate">
+<code class="descname">-fprofile-generate[</code><code class="descclassname">=<dirname>]</code><a class="headerlink" href="#cmdoption-fprofile-generate" title="Permalink to this definition">¶</a></dt>
+<dd><blockquote>
+<div><p>The <code class="docutils literal notranslate"><span class="pre">-fprofile-generate</span></code> and <code class="docutils literal notranslate"><span class="pre">-fprofile-generate=</span></code> flags will use
+an alternative instrumentation method for profile generation. When
+given a directory name, it generates the profile file
+<code class="docutils literal notranslate"><span class="pre">default_%m.profraw</span></code> in the directory named <code class="docutils literal notranslate"><span class="pre">dirname</span></code> if specified.
+If <code class="docutils literal notranslate"><span class="pre">dirname</span></code> does not exist, it will be created at runtime. <code class="docutils literal notranslate"><span class="pre">%m</span></code> specifier
+will be substituted with a unique id documented in step 2 above. In other words,
+with <code class="docutils literal notranslate"><span class="pre">-fprofile-generate[=<dirname>]</span></code> option, the ârawâ profile data automatic
+merging is turned on by default, so there will no longer any risk of profile
+clobbering from different running processes. For example,</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang++ -O2 -fprofile-generate<span class="o">=</span>yyy/zzz code.cc -o code
+</pre></div>
+</div>
+<p>When <code class="docutils literal notranslate"><span class="pre">code</span></code> is executed, the profile will be written to the file
+<code class="docutils literal notranslate"><span class="pre">yyy/zzz/default_xxxx.profraw</span></code>.</p>
+<p>To generate the profile data file with the compiler readable format, the
+<code class="docutils literal notranslate"><span class="pre">llvm-profdata</span></code> tool can be used with the profile directory as the input:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-profdata merge -output<span class="o">=</span>code.profdata yyy/zzz/
+</pre></div>
+</div>
+</div></blockquote>
+</div></blockquote>
+<p>If the user wants to turn off the auto-merging feature, or simply override the
+the profile dumping path specified at command line, the environment variable
+<code class="docutils literal notranslate"><span class="pre">LLVM_PROFILE_FILE</span></code> can still be used to override
+the directory and filename for the profile file at runtime.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fcs-profile-generate">
+<code class="descname">-fcs-profile-generate[</code><code class="descclassname">=<dirname>]</code><a class="headerlink" href="#cmdoption-fcs-profile-generate" title="Permalink to this definition">¶</a></dt>
+<dd><p>The <code class="docutils literal notranslate"><span class="pre">-fcs-profile-generate</span></code> and <code class="docutils literal notranslate"><span class="pre">-fcs-profile-generate=</span></code> flags will use
+the same instrumentation method, and generate the same profile as in the
+<code class="docutils literal notranslate"><span class="pre">-fprofile-generate</span></code> and <code class="docutils literal notranslate"><span class="pre">-fprofile-generate=</span></code> flags. The difference is
+that the instrumentation is performed after inlining so that the resulted
+profile has a better context sensitive information. They cannot be used
+together with <code class="docutils literal notranslate"><span class="pre">-fprofile-generate</span></code> and <code class="docutils literal notranslate"><span class="pre">-fprofile-generate=</span></code> flags.
+They are typically used in conjunction with <code class="docutils literal notranslate"><span class="pre">-fprofile-use</span></code> flag.
+The profile generated by <code class="docutils literal notranslate"><span class="pre">-fcs-profile-generate</span></code> and <code class="docutils literal notranslate"><span class="pre">-fprofile-generate</span></code>
+can be merged by llvm-profdata. A use example:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang++ -O2 -fprofile-generate<span class="o">=</span>yyy/zzz code.cc -o code
+<span class="gp">$</span> ./code
+<span class="gp">$</span> llvm-profdata merge -output<span class="o">=</span>code.profdata yyy/zzz/
+</pre></div>
+</div>
+<p>The first few steps are the same as that in <code class="docutils literal notranslate"><span class="pre">-fprofile-generate</span></code>
+compilation. Then perform a second round of instrumentation.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang++ -O2 -fprofile-use<span class="o">=</span>code.profdata -fcs-profile-generate<span class="o">=</span>sss/ttt <span class="se">\</span>
+ -o cs_code
+<span class="gp">$</span> ./cs_code
+<span class="gp">$</span> llvm-profdata merge -output<span class="o">=</span>cs_code.profdata sss/ttt code.profdata
+</pre></div>
+</div>
+<p>The resulted <code class="docutils literal notranslate"><span class="pre">cs_code.prodata</span></code> combines <code class="docutils literal notranslate"><span class="pre">code.profdata</span></code> and the profile
+generated from binary <code class="docutils literal notranslate"><span class="pre">cs_code</span></code>. Profile <code class="docutils literal notranslate"><span class="pre">cs_code.profata</span></code> can be used by
+<code class="docutils literal notranslate"><span class="pre">-fprofile-use</span></code> compilaton.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang++ -O2 -fprofile-use<span class="o">=</span>cs_code.profdata
+</pre></div>
+</div>
+<p>The above command will read both profiles to the compiler at the identical
+point of instrumenations.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fprofile-use">
+<code class="descname">-fprofile-use[</code><code class="descclassname">=<pathname>]</code><a class="headerlink" href="#cmdoption-fprofile-use" title="Permalink to this definition">¶</a></dt>
+<dd><p>Without any other arguments, <code class="docutils literal notranslate"><span class="pre">-fprofile-use</span></code> behaves identically to
+<code class="docutils literal notranslate"><span class="pre">-fprofile-instr-use</span></code>. Otherwise, if <code class="docutils literal notranslate"><span class="pre">pathname</span></code> is the full path to a
+profile file, it reads from that file. If <code class="docutils literal notranslate"><span class="pre">pathname</span></code> is a directory name,
+it reads from <code class="docutils literal notranslate"><span class="pre">pathname/default.profdata</span></code>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="disabling-instrumentation">
+<h4><a class="toc-backref" href="#id43">Disabling Instrumentation</a><a class="headerlink" href="#disabling-instrumentation" title="Permalink to this headline">¶</a></h4>
+<p>In certain situations, it may be useful to disable profile generation or use
+for specific files in a build, without affecting the main compilation flags
+used for the other files in the project.</p>
+<p>In these cases, you can use the flag <code class="docutils literal notranslate"><span class="pre">-fno-profile-instr-generate</span></code> (or
+<code class="docutils literal notranslate"><span class="pre">-fno-profile-generate</span></code>) to disable profile generation, and
+<code class="docutils literal notranslate"><span class="pre">-fno-profile-instr-use</span></code> (or <code class="docutils literal notranslate"><span class="pre">-fno-profile-use</span></code>) to disable profile use.</p>
+<p>Note that these flags should appear after the corresponding profile
+flags to have an effect.</p>
+</div>
+<div class="section" id="profile-remapping">
+<h4><a class="toc-backref" href="#id44">Profile remapping</a><a class="headerlink" href="#profile-remapping" title="Permalink to this headline">¶</a></h4>
+<p>When the program is compiled after a change that affects many symbol names,
+pre-existing profile data may no longer match the program. For example:</p>
+<blockquote>
+<div><ul class="simple">
+<li>switching from libstdc++ to libc++ will result in the mangled names of all
+functions taking standard library types to change</li>
+<li>renaming a widely-used type in C++ will result in the mangled names of all
+functions that have parameters involving that type to change</li>
+<li>moving from a 32-bit compilation to a 64-bit compilation may change the
+underlying type of <code class="docutils literal notranslate"><span class="pre">size_t</span></code> and similar types, resulting in changes to
+manglings</li>
+</ul>
+</div></blockquote>
+<p>Clang allows use of a profile remapping file to specify that such differences
+in mangled names should be ignored when matching the profile data against the
+program.</p>
+<dl class="option">
+<dt id="cmdoption-fprofile-remapping-file">
+<code class="descname">-fprofile-remapping-file</code><code class="descclassname">=<file></code><a class="headerlink" href="#cmdoption-fprofile-remapping-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specifies a file containing profile remapping information, that will be
+used to match mangled names in the profile data to mangled names in the
+program.</p>
+</dd></dl>
+
+<p>The profile remapping file is a text file containing lines of the form</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>fragmentkind fragment1 fragment2
+</pre></div>
+</div>
+<p>where <code class="docutils literal notranslate"><span class="pre">fragmentkind</span></code> is one of <code class="docutils literal notranslate"><span class="pre">name</span></code>, <code class="docutils literal notranslate"><span class="pre">type</span></code>, or <code class="docutils literal notranslate"><span class="pre">encoding</span></code>,
+indicating whether the following mangled name fragments are
+<<a class="reference external" href="https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name">name</a>>s,
+<<a class="reference external" href="https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type">type</a>>s, or
+<<a class="reference external" href="https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding">encoding</a>>s,
+respectively.
+Blank lines and lines starting with <code class="docutils literal notranslate"><span class="pre">#</span></code> are ignored.</p>
+<p>For convenience, built-in <substitution>s such as <code class="docutils literal notranslate"><span class="pre">St</span></code> and <code class="docutils literal notranslate"><span class="pre">Ss</span></code>
+are accepted as <name>s (even though they technically are not <name>s).</p>
+<p>For example, to specify that <code class="docutils literal notranslate"><span class="pre">absl::string_view</span></code> and <code class="docutils literal notranslate"><span class="pre">std::string_view</span></code>
+should be treated as equivalent when matching profile data, the following
+remapping file could be used:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># absl::string_view is considered equivalent to std::string_view
+type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE
+
+# std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
+name 3std St3__1
+name 3std St7__cxx11
+</pre></div>
+</div>
+<p>Matching profile data using a profile remapping file is supported on a
+best-effort basis. For example, information regarding indirect call targets is
+currently not remapped. For best results, you are encouraged to generate new
+profile data matching the updated program, or to remap the profile data
+using the <code class="docutils literal notranslate"><span class="pre">llvm-cxxmap</span></code> and <code class="docutils literal notranslate"><span class="pre">llvm-profdata</span> <span class="pre">merge</span></code> tools.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Profile data remapping support is currently only implemented for LLVMâs
+new pass manager, which can be enabled with
+<code class="docutils literal notranslate"><span class="pre">-fexperimental-new-pass-manager</span></code>.</p>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Profile data remapping is currently only supported for C++ mangled names
+following the Itanium C++ ABI mangling scheme. This covers all C++ targets
+supported by Clang other than Windows.</p>
+</div>
+</div>
+</div>
+<div class="section" id="gcov-based-profiling">
+<h3><a class="toc-backref" href="#id45">GCOV-based Profiling</a><a class="headerlink" href="#gcov-based-profiling" title="Permalink to this headline">¶</a></h3>
+<p>GCOV is a test coverage program, it helps to know how often a line of code
+is executed. When instrumenting the code with <code class="docutils literal notranslate"><span class="pre">--coverage</span></code> option, some
+counters are added for each edge linking basic blocks.</p>
+<p>At compile time, gcno files are generated containing information about
+blocks and edges between them. At runtime the counters are incremented and at
+exit the counters are dumped in gcda files.</p>
+<p>The tool <code class="docutils literal notranslate"><span class="pre">llvm-cov</span> <span class="pre">gcov</span></code> will parse gcno, gcda and source files to generate
+a report <code class="docutils literal notranslate"><span class="pre">.c.gcov</span></code>.</p>
+<dl class="option">
+<dt id="cmdoption-fprofile-filter-files">
+<code class="descname">-fprofile-filter-files</code><code class="descclassname">=[regexes]</code><a class="headerlink" href="#cmdoption-fprofile-filter-files" title="Permalink to this definition">¶</a></dt>
+<dd><p>Define a list of regexes separated by a semi-colon.
+If a file name matches any of the regexes then the file is instrumented.</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang --coverage -fprofile-filter-files<span class="o">=</span><span class="s2">".*\.c</span>$<span class="s2">"</span> foo.c
+</pre></div>
+</div>
+</div></blockquote>
+<p>For example, this will only instrument files finishing with <code class="docutils literal notranslate"><span class="pre">.c</span></code>, skipping <code class="docutils literal notranslate"><span class="pre">.h</span></code> files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fprofile-exclude-files">
+<code class="descname">-fprofile-exclude-files</code><code class="descclassname">=[regexes]</code><a class="headerlink" href="#cmdoption-fprofile-exclude-files" title="Permalink to this definition">¶</a></dt>
+<dd><p>Define a list of regexes separated by a semi-colon.
+If a file name doesnât match all the regexes then the file is instrumented.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang --coverage -fprofile-exclude-files<span class="o">=</span><span class="s2">"^/usr/include/.*</span>$<span class="s2">"</span> foo.c
+</pre></div>
+</div>
+<p>For example, this will instrument all the files except the ones in <code class="docutils literal notranslate"><span class="pre">/usr/include</span></code>.</p>
+</dd></dl>
+
+<p>If both options are used then a file is instrumented if its name matches any
+of the regexes from <code class="docutils literal notranslate"><span class="pre">-fprofile-filter-list</span></code> and doesnât match all the regexes
+from <code class="docutils literal notranslate"><span class="pre">-fprofile-exclude-list</span></code>.</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang --coverage -fprofile-exclude-files<span class="o">=</span><span class="s2">"^/usr/include/.*</span>$<span class="s2">"</span> <span class="se">\</span>
+ -fprofile-filter-files<span class="o">=</span><span class="s2">"^/usr/.*</span>$<span class="s2">"</span>
+</pre></div>
+</div>
+<p>In that case <code class="docutils literal notranslate"><span class="pre">/usr/foo/oof.h</span></code> is instrumented since it matches the filter regex and
+doesnât match the exclude regex, but <code class="docutils literal notranslate"><span class="pre">/usr/include/foo.h</span></code> doesnât since it matches
+the exclude regex.</p>
+</div>
+<div class="section" id="controlling-debug-information">
+<h3><a class="toc-backref" href="#id46">Controlling Debug Information</a><a class="headerlink" href="#controlling-debug-information" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="controlling-size-of-debug-information">
+<h4><a class="toc-backref" href="#id47">Controlling Size of Debug Information</a><a class="headerlink" href="#controlling-size-of-debug-information" title="Permalink to this headline">¶</a></h4>
+<p>Debug info kind generated by Clang can be set by one of the flags listed
+below. If multiple flags are present, the last one is used.</p>
+<dl class="option">
+<dt id="cmdoption-g0">
+<code class="descname">-g0</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-g0" title="Permalink to this definition">¶</a></dt>
+<dd><p>Donât generate any debug info (default).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-gline-tables-only">
+<code class="descname">-gline-tables-only</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-gline-tables-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate line number tables only.</p>
+<p>This kind of debug info allows to obtain stack traces with function names,
+file names and line numbers (by such tools as <code class="docutils literal notranslate"><span class="pre">gdb</span></code> or <code class="docutils literal notranslate"><span class="pre">addr2line</span></code>). It
+doesnât contain any other data (e.g. description of local variables or
+function parameters).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fstandalone-debug">
+<code class="descname">-fstandalone-debug</code><code class="descclassname"></code><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 <strong>-fstandalone-debug</strong> option turns off these optimizations.
+This is useful when working with 3rd-party libraries that donât come
+with debug information. 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-fno-standalone-debug">
+<code class="descname">-fno-standalone-debug</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fno-standalone-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>On Darwin <strong>-fstandalone-debug</strong> is enabled by default. The
+<strong>-fno-standalone-debug</strong> option can be used to get to turn on the
+vtable-based optimization described above.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-g">
+<code class="descname">-g</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-g" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate complete debug info.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="controlling-macro-debug-info-generation">
+<h4><a class="toc-backref" href="#id48">Controlling Macro Debug Info Generation</a><a class="headerlink" href="#controlling-macro-debug-info-generation" title="Permalink to this headline">¶</a></h4>
+<p>Debug info for C preprocessor macros increases the size of debug information in
+the binary. Macro debug info generated by Clang can be controlled by the flags
+listed below.</p>
+<dl class="option">
+<dt id="cmdoption-fdebug-macro">
+<code class="descname">-fdebug-macro</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fdebug-macro" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate debug info for preprocessor macros. This flag is discarded when
+<strong>-g0</strong> is enabled.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-debug-macro">
+<code class="descname">-fno-debug-macro</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fno-debug-macro" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not generate debug info for preprocessor macros (default).</p>
+</dd></dl>
+
+</div>
+<div class="section" id="controlling-debugger-tuning">
+<h4><a class="toc-backref" href="#id49">Controlling Debugger âTuningâ</a><a class="headerlink" href="#controlling-debugger-tuning" title="Permalink to this headline">¶</a></h4>
+<p>While Clang generally emits standard DWARF debug info (<a class="reference external" href="http://dwarfstd.org">http://dwarfstd.org</a>),
+different debuggers may know how to take advantage of different specific DWARF
+features. You can âtuneâ the debug info for one of several different debuggers.</p>
+<dl class="option">
+<dt id="cmdoption-ggdb">
+<code class="descname">-ggdb</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-glldb</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-gsce</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-ggdb" title="Permalink to this definition">¶</a></dt>
+<dd><p>Tune the debug info for the <code class="docutils literal notranslate"><span class="pre">gdb</span></code>, <code class="docutils literal notranslate"><span class="pre">lldb</span></code>, or Sony PlayStation®
+debugger, respectively. Each of these options implies <strong>-g</strong>. (Therefore, if
+you want both <strong>-gline-tables-only</strong> and debugger tuning, the tuning option
+must come first.)</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="controlling-llvm-ir-output">
+<h3><a class="toc-backref" href="#id50">Controlling LLVM IR Output</a><a class="headerlink" href="#controlling-llvm-ir-output" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="controlling-value-names-in-llvm-ir">
+<h4><a class="toc-backref" href="#id51">Controlling Value Names in LLVM IR</a><a class="headerlink" href="#controlling-value-names-in-llvm-ir" title="Permalink to this headline">¶</a></h4>
+<p>Emitting value names in LLVM IR increases the size and verbosity of the IR.
+By default, value names are only emitted in assertion-enabled builds of Clang.
+However, when reading IR it can be useful to re-enable the emission of value
+names to improve readability.</p>
+<dl class="option">
+<dt id="cmdoption-fdiscard-value-names">
+<code class="descname">-fdiscard-value-names</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fdiscard-value-names" title="Permalink to this definition">¶</a></dt>
+<dd><p>Discard value names when generating LLVM IR.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-discard-value-names">
+<code class="descname">-fno-discard-value-names</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fno-discard-value-names" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not discard value names when generating LLVM IR. This option can be used
+to re-enable names for release builds of Clang.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="comment-parsing-options">
+<h3><a class="toc-backref" href="#id52">Comment Parsing Options</a><a class="headerlink" href="#comment-parsing-options" title="Permalink to this headline">¶</a></h3>
+<p>Clang parses Doxygen and non-Doxygen style documentation comments and attaches
+them to the appropriate declaration nodes. By default, it only parses
+Doxygen-style comments and ignores ordinary comments starting with <code class="docutils literal notranslate"><span class="pre">//</span></code> and
+<code class="docutils literal notranslate"><span class="pre">/*</span></code>.</p>
+<dl class="option">
+<dt id="cmdoption-wdocumentation">
+<code class="descname">-Wdocumentation</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-wdocumentation" title="Permalink to this definition">¶</a></dt>
+<dd><p>Emit warnings about use of documentation comments. This warning group is off
+by default.</p>
+<p>This includes checking that <code class="docutils literal notranslate"><span class="pre">\param</span></code> commands name parameters that actually
+present in the function signature, checking that <code class="docutils literal notranslate"><span class="pre">\returns</span></code> is used only on
+functions that actually return a value etc.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-wno-documentation-unknown-command">
+<code class="descname">-Wno-documentation-unknown-command</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-wno-documentation-unknown-command" title="Permalink to this definition">¶</a></dt>
+<dd><p>Donât warn when encountering an unknown Doxygen command.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fparse-all-comments">
+<code class="descname">-fparse-all-comments</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fparse-all-comments" title="Permalink to this definition">¶</a></dt>
+<dd><p>Parse all comments as documentation comments (including ordinary comments
+starting with <code class="docutils literal notranslate"><span class="pre">//</span></code> and <code class="docutils literal notranslate"><span class="pre">/*</span></code>).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fcomment-block-commands">
+<code class="descname">-fcomment-block-commands</code><code class="descclassname">=[commands]</code><a class="headerlink" href="#cmdoption-fcomment-block-commands" title="Permalink to this definition">¶</a></dt>
+<dd><p>Define custom documentation commands as block commands. This allows Clang to
+construct the correct AST for these custom commands, and silences warnings
+about unknown commands. Several commands must be separated by a comma
+<em>without trailing space</em>; e.g. <code class="docutils literal notranslate"><span class="pre">-fcomment-block-commands=foo,bar</span></code> defines
+custom commands <code class="docutils literal notranslate"><span class="pre">\foo</span></code> and <code class="docutils literal notranslate"><span class="pre">\bar</span></code>.</p>
+<p>It is also possible to use <code class="docutils literal notranslate"><span class="pre">-fcomment-block-commands</span></code> several times; e.g.
+<code class="docutils literal notranslate"><span class="pre">-fcomment-block-commands=foo</span> <span class="pre">-fcomment-block-commands=bar</span></code> does the same
+as above.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="c-language-features">
+<span id="c"></span><h2><a class="toc-backref" href="#id53">C Language Features</a><a class="headerlink" href="#c-language-features" title="Permalink to this headline">¶</a></h2>
+<p>The support for standard C in clang is feature-complete except for the
+C99 floating-point pragmas.</p>
+<div class="section" id="extensions-supported-by-clang">
+<h3><a class="toc-backref" href="#id54">Extensions supported by clang</a><a class="headerlink" href="#extensions-supported-by-clang" title="Permalink to this headline">¶</a></h3>
+<p>See <a class="reference internal" href="LanguageExtensions.html"><span class="doc">Clang Language Extensions</span></a>.</p>
+</div>
+<div class="section" id="differences-between-various-standard-modes">
+<h3><a class="toc-backref" href="#id55">Differences between various standard modes</a><a class="headerlink" href="#differences-between-various-standard-modes" title="Permalink to this headline">¶</a></h3>
+<p>clang supports the -std option, which changes what language mode clang
+uses. The supported modes for C are c89, gnu89, c99, gnu99, c11, gnu11,
+c17, gnu17, and various aliases for those modes. If no -std option is
+specified, clang defaults to gnu11 mode. Many C99 and C11 features are
+supported in earlier modes as a conforming extension, with a warning. Use
+<code class="docutils literal notranslate"><span class="pre">-pedantic-errors</span></code> to request an error if a feature from a later standard
+revision is used in an earlier mode.</p>
+<p>Differences between all <code class="docutils literal notranslate"><span class="pre">c*</span></code> and <code class="docutils literal notranslate"><span class="pre">gnu*</span></code> modes:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">c*</span></code> modes define â<code class="docutils literal notranslate"><span class="pre">__STRICT_ANSI__</span></code>â.</li>
+<li>Target-specific defines not prefixed by underscores, like âlinuxâ,
+are defined in <code class="docutils literal notranslate"><span class="pre">gnu*</span></code> modes.</li>
+<li>Trigraphs default to being off in <code class="docutils literal notranslate"><span class="pre">gnu*</span></code> modes; they can be enabled by
+the -trigraphs option.</li>
+<li>The parser recognizes âasmâ and âtypeofâ as keywords in <code class="docutils literal notranslate"><span class="pre">gnu*</span></code> modes;
+the variants â<code class="docutils literal notranslate"><span class="pre">__asm__</span></code>â and â<code class="docutils literal notranslate"><span class="pre">__typeof__</span></code>â are recognized in all
+modes.</li>
+<li>The Apple âblocksâ extension is recognized by default in <code class="docutils literal notranslate"><span class="pre">gnu*</span></code> modes
+on some platforms; it can be enabled in any mode with the â-fblocksâ
+option.</li>
+<li>Arrays that are VLAâs according to the standard, but which can be
+constant folded by the frontend are treated as fixed size arrays.
+This occurs for things like âint X[(1, 2)];â, which is technically a
+VLA. <code class="docutils literal notranslate"><span class="pre">c*</span></code> modes are strictly compliant and treat these as VLAs.</li>
+</ul>
+<p>Differences between <code class="docutils literal notranslate"><span class="pre">*89</span></code> and <code class="docutils literal notranslate"><span class="pre">*99</span></code> modes:</p>
+<ul class="simple">
+<li>The <code class="docutils literal notranslate"><span class="pre">*99</span></code> modes default to implementing âinlineâ as specified in C99,
+while the <code class="docutils literal notranslate"><span class="pre">*89</span></code> modes implement the GNU version. This can be
+overridden for individual functions with the <code class="docutils literal notranslate"><span class="pre">__gnu_inline__</span></code>
+attribute.</li>
+<li>Digraphs are not recognized in c89 mode.</li>
+<li>The scope of names defined inside a âforâ, âifâ, âswitchâ, âwhileâ,
+or âdoâ statement is different. (example: â<code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">((struct</span> <span class="pre">x</span> <span class="pre">{int</span>
+<span class="pre">x;}*)0)</span> <span class="pre">{}</span></code>â.)</li>
+<li><code class="docutils literal notranslate"><span class="pre">__STDC_VERSION__</span></code> is not defined in <code class="docutils literal notranslate"><span class="pre">*89</span></code> modes.</li>
+<li>âinlineâ is not recognized as a keyword in c89 mode.</li>
+<li>ârestrictâ is not recognized as a keyword in <code class="docutils literal notranslate"><span class="pre">*89</span></code> modes.</li>
+<li>Commas are allowed in integer constant expressions in <code class="docutils literal notranslate"><span class="pre">*99</span></code> modes.</li>
+<li>Arrays which are not lvalues are not implicitly promoted to pointers
+in <code class="docutils literal notranslate"><span class="pre">*89</span></code> modes.</li>
+<li>Some warnings are different.</li>
+</ul>
+<p>Differences between <code class="docutils literal notranslate"><span class="pre">*99</span></code> and <code class="docutils literal notranslate"><span class="pre">*11</span></code> modes:</p>
+<ul class="simple">
+<li>Warnings for use of C11 features are disabled.</li>
+<li><code class="docutils literal notranslate"><span class="pre">__STDC_VERSION__</span></code> is defined to <code class="docutils literal notranslate"><span class="pre">201112L</span></code> rather than <code class="docutils literal notranslate"><span class="pre">199901L</span></code>.</li>
+</ul>
+<p>Differences between <code class="docutils literal notranslate"><span class="pre">*11</span></code> and <code class="docutils literal notranslate"><span class="pre">*17</span></code> modes:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">__STDC_VERSION__</span></code> is defined to <code class="docutils literal notranslate"><span class="pre">201710L</span></code> rather than <code class="docutils literal notranslate"><span class="pre">201112L</span></code>.</li>
+</ul>
+</div>
+<div class="section" id="gcc-extensions-not-implemented-yet">
+<h3><a class="toc-backref" href="#id56">GCC extensions not implemented yet</a><a class="headerlink" href="#gcc-extensions-not-implemented-yet" title="Permalink to this headline">¶</a></h3>
+<p>clang tries to be compatible with gcc as much as possible, but some gcc
+extensions are not implemented yet:</p>
+<ul>
+<li><p class="first">clang does not support decimal floating point types (<code class="docutils literal notranslate"><span class="pre">_Decimal32</span></code> and
+friends) or fixed-point types (<code class="docutils literal notranslate"><span class="pre">_Fract</span></code> and friends); nobody has
+expressed interest in these features yet, so itâs hard to say when
+they will be implemented.</p>
+</li>
+<li><p class="first">clang does not support nested functions; this is a complex feature
+which is infrequently used, so it is unlikely to be implemented
+anytime soon. In C++11 it can be emulated by assigning lambda
+functions to local variables, e.g:</p>
+<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="k">auto</span> <span class="k">const</span> <span class="n">local_function</span> <span class="o">=</span> <span class="p">[</span><span class="o">&</span><span class="p">](</span><span class="kt">int</span> <span class="n">parameter</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Do something</span>
+<span class="p">};</span>
+<span class="p">...</span>
+<span class="n">local_function</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">clang only supports global register variables when the register specified
+is non-allocatable (e.g. the stack pointer). Support for general global
+register variables is unlikely to be implemented soon because it requires
+additional LLVM backend support.</p>
+</li>
+<li><p class="first">clang does not support static initialization of flexible array
+members. This appears to be a rarely used extension, but could be
+implemented pending user demand.</p>
+</li>
+<li><p class="first">clang does not support
+<code class="docutils literal notranslate"><span class="pre">__builtin_va_arg_pack</span></code>/<code class="docutils literal notranslate"><span class="pre">__builtin_va_arg_pack_len</span></code>. This is
+used rarely, but in some potentially interesting places, like the
+glibc headers, so it may be implemented pending user demand. Note
+that because clang pretends to be like GCC 4.2, and this extension
+was introduced in 4.3, the glibc headers will not try to use this
+extension with clang at the moment.</p>
+</li>
+<li><p class="first">clang does not support the gcc extension for forward-declaring
+function parameters; this has not shown up in any real-world code
+yet, though, so it might never be implemented.</p>
+</li>
+</ul>
+<p>This is not a complete list; if you find an unsupported extension
+missing from this list, please send an e-mail to cfe-dev. This list
+currently excludes C++; see <a class="reference internal" href="#cxx"><span class="std std-ref">C++ Language Features</span></a>. Also, this
+list does not include bugs in mostly-implemented features; please see
+the <a class="reference external" href="https://bugs.llvm.org/buglist.cgi?quicksearch=product%3Aclang+component%3A-New%2BBugs%2CAST%2CBasic%2CDriver%2CHeaders%2CLLVM%2BCodeGen%2Cparser%2Cpreprocessor%2CSemantic%2BAnalyzer">bug
+tracker</a>
+for known existing bugs (FIXME: Is there a section for bug-reporting
+guidelines somewhere?).</p>
+</div>
+<div class="section" id="intentionally-unsupported-gcc-extensions">
+<h3><a class="toc-backref" href="#id57">Intentionally unsupported GCC extensions</a><a class="headerlink" href="#intentionally-unsupported-gcc-extensions" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>clang does not support the gcc extension that allows variable-length
+arrays in structures. This is for a few reasons: one, it is tricky to
+implement, two, the extension is completely undocumented, and three,
+the extension appears to be rarely used. Note that clang <em>does</em>
+support flexible array members (arrays with a zero or unspecified
+size at the end of a structure).</li>
+<li>clang does not have an equivalent to gccâs âfoldâ; this means that
+clang doesnât accept some constructs gcc might accept in contexts
+where a constant expression is required, like âx-xâ where x is a
+variable.</li>
+<li>clang does not support <code class="docutils literal notranslate"><span class="pre">__builtin_apply</span></code> and friends; this extension
+is extremely obscure and difficult to implement reliably.</li>
+</ul>
+</div>
+<div class="section" id="microsoft-extensions">
+<span id="c-ms"></span><h3><a class="toc-backref" href="#id58">Microsoft extensions</a><a class="headerlink" href="#microsoft-extensions" title="Permalink to this headline">¶</a></h3>
+<p>clang has support for many extensions from Microsoft Visual C++. To enable these
+extensions, use the <code class="docutils literal notranslate"><span class="pre">-fms-extensions</span></code> command-line option. This is the default
+for Windows targets. Clang does not implement every pragma or declspec provided
+by MSVC, but the popular ones, such as <code class="docutils literal notranslate"><span class="pre">__declspec(dllexport)</span></code> and <code class="docutils literal notranslate"><span class="pre">#pragma</span>
+<span class="pre">comment(lib)</span></code> are well supported.</p>
+<p>clang has a <code class="docutils literal notranslate"><span class="pre">-fms-compatibility</span></code> flag that makes clang accept enough
+invalid C++ to be able to parse most Microsoft headers. For example, it
+allows <a class="reference external" href="https://clang.llvm.org/compatibility.html#dep_lookup_bases">unqualified lookup of dependent base class members</a>, which is
+a common compatibility issue with clang. This flag is enabled by default
+for Windows targets.</p>
+<p><code class="docutils literal notranslate"><span class="pre">-fdelayed-template-parsing</span></code> lets clang delay parsing of function template
+definitions until the end of a translation unit. This flag is enabled by
+default for Windows targets.</p>
+<p>For compatibility with existing code that compiles with MSVC, clang defines the
+<code class="docutils literal notranslate"><span class="pre">_MSC_VER</span></code> and <code class="docutils literal notranslate"><span class="pre">_MSC_FULL_VER</span></code> macros. These default to the values of 1800
+and 180000000 respectively, making clang look like an early release of Visual
+C++ 2013. The <code class="docutils literal notranslate"><span class="pre">-fms-compatibility-version=</span></code> flag overrides these values. It
+accepts a dotted version tuple, such as 19.00.23506. Changing the MSVC
+compatibility version makes clang behave more like that version of MSVC. For
+example, <code class="docutils literal notranslate"><span class="pre">-fms-compatibility-version=19</span></code> will enable C++14 features and define
+<code class="docutils literal notranslate"><span class="pre">char16_t</span></code> and <code class="docutils literal notranslate"><span class="pre">char32_t</span></code> as builtin types.</p>
+</div>
+</div>
+<div class="section" id="cxx">
+<span id="id4"></span><h2><a class="toc-backref" href="#id59">C++ Language Features</a><a class="headerlink" href="#cxx" title="Permalink to this headline">¶</a></h2>
+<p>clang fully implements all of standard C++98 except for exported
+templates (which were removed in C++11), and all of standard C++11
+and the current draft standard for C++1y.</p>
+<div class="section" id="controlling-implementation-limits">
+<h3><a class="toc-backref" href="#id60">Controlling implementation limits</a><a class="headerlink" href="#controlling-implementation-limits" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-fbracket-depth">
+<code class="descname">-fbracket-depth</code><code class="descclassname">=N</code><a class="headerlink" href="#cmdoption-fbracket-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for nested parentheses, brackets, and braces to N. The
+default is 256.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fconstexpr-depth">
+<code class="descname">-fconstexpr-depth</code><code class="descclassname">=N</code><a class="headerlink" href="#cmdoption-fconstexpr-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for recursive constexpr function invocations to N. The
+default is 512.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fconstexpr-steps">
+<code class="descname">-fconstexpr-steps</code><code class="descclassname">=N</code><a class="headerlink" href="#cmdoption-fconstexpr-steps" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for the number of full-expressions evaluated in a single
+constant expression evaluation. The default is 1048576.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ftemplate-depth">
+<code class="descname">-ftemplate-depth</code><code class="descclassname">=N</code><a class="headerlink" href="#cmdoption-ftemplate-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for recursively nested template instantiations to N. The
+default is 1024.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-foperator-arrow-depth">
+<code class="descname">-foperator-arrow-depth</code><code class="descclassname">=N</code><a class="headerlink" href="#cmdoption-foperator-arrow-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sets the limit for iterative calls to âoperator->â functions to N. The
+default is 256.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="objective-c-language-features">
+<span id="objc"></span><h2><a class="toc-backref" href="#id61">Objective-C Language Features</a><a class="headerlink" href="#objective-c-language-features" title="Permalink to this headline">¶</a></h2>
+</div>
+<div class="section" id="objcxx">
+<span id="id5"></span><h2><a class="toc-backref" href="#id62">Objective-C++ Language Features</a><a class="headerlink" href="#objcxx" title="Permalink to this headline">¶</a></h2>
+</div>
+<div class="section" id="openmp-features">
+<span id="openmp"></span><h2><a class="toc-backref" href="#id63">OpenMP Features</a><a class="headerlink" href="#openmp-features" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports all OpenMP 4.5 directives and clauses. See <a class="reference internal" href="OpenMPSupport.html"><span class="doc">OpenMP Support</span></a>
+for additional details.</p>
+<p>Use <cite>-fopenmp</cite> to enable OpenMP. Support for OpenMP can be disabled with
+<cite>-fno-openmp</cite>.</p>
+<p>Use <cite>-fopenmp-simd</cite> to enable OpenMP simd features only, without linking
+the runtime library; for combined constructs
+(e.g. <code class="docutils literal notranslate"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">parallel</span> <span class="pre">for</span> <span class="pre">simd</span></code>) the non-simd directives and clauses
+will be ignored. This can be disabled with <cite>-fno-openmp-simd</cite>.</p>
+<div class="section" id="id6">
+<h3><a class="toc-backref" href="#id64">Controlling implementation limits</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-fopenmp-use-tls">
+<code class="descname">-fopenmp-use-tls</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-fopenmp-use-tls" title="Permalink to this definition">¶</a></dt>
+<dd><p>Controls code generation for OpenMP threadprivate variables. In presence of
+this option all threadprivate variables are generated the same way as thread
+local variables, using TLS support. If <cite>-fno-openmp-use-tls</cite>
+is provided or target does not support TLS, code generation for threadprivate
+variables relies on OpenMP runtime library.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="opencl-features">
+<span id="opencl"></span><h2><a class="toc-backref" href="#id65">OpenCL Features</a><a class="headerlink" href="#opencl-features" title="Permalink to this headline">¶</a></h2>
+<p>Clang can be used to compile OpenCL kernels for execution on a device
+(e.g. GPU). It is possible to compile the kernel into a binary (e.g. for AMD or
+Nvidia targets) that can be uploaded to run directly on a device (e.g. using
+<a class="reference external" href="https://www.khronos.org/registry/OpenCL/specs/opencl-1.1.pdf#111">clCreateProgramWithBinary</a>) or
+into generic bitcode files loadable into other toolchains.</p>
+<p>Compiling to a binary using the default target from the installation can be done
+as follows:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">"kernel void k(){}"</span> > test.cl
+<span class="gp">$</span> clang test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Compiling for a specific target can be done by specifying the triple corresponding
+to the target, for example:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -target nvptx64-unknown-unknown test.cl
+<span class="gp">$</span> clang -target amdgcn-amd-amdhsa -mcpu<span class="o">=</span>gfx900 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Compiling to bitcode can be done as follows:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -c -emit-llvm test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>This will produce a generic test.bc file that can be used in vendor toolchains
+to perform machine code generation.</p>
+<p>Clang currently supports OpenCL C language standards up to v2.0. Starting from
+clang 9 a C++ mode is available for OpenCL (see <a class="reference internal" href="#opencl-cpp"><span class="std std-ref">C++ for OpenCL</span></a>).</p>
+<div class="section" id="opencl-specific-options">
+<h3><a class="toc-backref" href="#id66">OpenCL Specific Options</a><a class="headerlink" href="#opencl-specific-options" title="Permalink to this headline">¶</a></h3>
+<p>Most of the OpenCL build options from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf#200">the specification v2.0 section 5.8.4</a> are available.</p>
+<p>Examples:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -cl-std<span class="o">=</span>CL2.0 -cl-single-precision-constant test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Some extra options are available to support special OpenCL features.</p>
+<dl class="option">
+<dt id="cmdoption-finclude-default-header">
+<code class="descname">-finclude-default-header</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-finclude-default-header" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Loads standard includes during compilations. By default OpenCL headers are not
+loaded and therefore standard library includes are not available. To load them
+automatically a flag has been added to the frontend (see also <a class="reference internal" href="#opencl-header"><span class="std std-ref">the section
+on the OpenCL Header</span></a>):</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -Xclang -finclude-default-header test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Alternatively <code class="docutils literal notranslate"><span class="pre">-include</span></code> or <code class="docutils literal notranslate"><span class="pre">-I</span></code> followed by the path to the header location
+can be given manually.</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -I<path to clang>/lib/Headers/opencl-c.h test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>In this case the kernel code should contain <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre"><opencl-c.h></span></code> just as a
+regular C include.</p>
+<span class="target" id="opencl-cl-ext"></span><dl class="option">
+<dt id="cmdoption-cl-ext">
+<code class="descname">-cl-ext</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-cl-ext" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Disables support of OpenCL extensions. All OpenCL targets provide a list
+of extensions that they support. Clang allows to amend this using the <code class="docutils literal notranslate"><span class="pre">-cl-ext</span></code>
+flag with a comma-separated list of extensions prefixed with <code class="docutils literal notranslate"><span class="pre">'+'</span></code> or <code class="docutils literal notranslate"><span class="pre">'-'</span></code>.
+The syntax: <code class="docutils literal notranslate"><span class="pre">-cl-ext=<(['-'|'+']<extension>[,])+></span></code>, where extensions
+can be either one of <a class="reference external" href="https://www.khronos.org/registry/cl/sdk/2.0/docs/man/xhtml/EXTENSION.html">the OpenCL specification extensions</a>
+or any known vendor extension. Alternatively, <code class="docutils literal notranslate"><span class="pre">'all'</span></code> can be used to enable
+or disable all known extensions.
+Example disabling double support for the 64-bit SPIR target:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -cc1 -triple spir64-unknown-unknown -cl-ext<span class="o">=</span>-cl_khr_fp64 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Enabling all extensions except double support in R600 AMD GPU can be done using:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -cc1 -triple r600-unknown-unknown -cl-ext<span class="o">=</span>-all,+cl_khr_fp16 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<span class="target" id="opencl-fake-address-space-map"></span><dl class="option">
+<dt id="cmdoption-ffake-address-space-map">
+<code class="descname">-ffake-address-space-map</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-ffake-address-space-map" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Overrides the target address space map with a fake map.
+This allows adding explicit address space IDs to the bitcode for non-segmented
+memory architectures that donât have separate IDs for each of the OpenCL
+logical address spaces by default. Passing <code class="docutils literal notranslate"><span class="pre">-ffake-address-space-map</span></code> will
+add/override address spaces of the target compiled for with the following values:
+<code class="docutils literal notranslate"><span class="pre">1-global</span></code>, <code class="docutils literal notranslate"><span class="pre">2-constant</span></code>, <code class="docutils literal notranslate"><span class="pre">3-local</span></code>, <code class="docutils literal notranslate"><span class="pre">4-generic</span></code>. The private address
+space is represented by the absence of an address space attribute in the IR (see
+also <a class="reference internal" href="#opencl-addrsp"><span class="std std-ref">the section on the address space attribute</span></a>).</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -ffake-address-space-map test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Some other flags used for the compilation for C can also be passed while
+compiling for OpenCL, examples: <code class="docutils literal notranslate"><span class="pre">-c</span></code>, <code class="docutils literal notranslate"><span class="pre">-O<1-4|s></span></code>, <code class="docutils literal notranslate"><span class="pre">-o</span></code>, <code class="docutils literal notranslate"><span class="pre">-emit-llvm</span></code>, etc.</p>
+</div>
+<div class="section" id="opencl-targets">
+<h3><a class="toc-backref" href="#id67">OpenCL Targets</a><a class="headerlink" href="#opencl-targets" title="Permalink to this headline">¶</a></h3>
+<p>OpenCL targets are derived from the regular Clang target classes. The OpenCL
+specific parts of the target representation provide address space mapping as
+well as a set of supported extensions.</p>
+<div class="section" id="specific-targets">
+<h4><a class="toc-backref" href="#id68">Specific Targets</a><a class="headerlink" href="#specific-targets" title="Permalink to this headline">¶</a></h4>
+<p>There is a set of concrete HW architectures that OpenCL can be compiled for.</p>
+<ul>
+<li><p class="first">For AMD target:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -target amdgcn-amd-amdhsa -mcpu<span class="o">=</span>gfx900 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+</li>
+<li><p class="first">For Nvidia architectures:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -target nvptx64-unknown-unknown test.cl
+</pre></div>
+</div>
+</div></blockquote>
+</li>
+</ul>
+</div>
+<div class="section" id="generic-targets">
+<h4><a class="toc-backref" href="#id69">Generic Targets</a><a class="headerlink" href="#generic-targets" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><p class="first">SPIR is available as a generic target to allow portable bitcode to be produced
+that can be used across GPU toolchains. The implementation follows <a class="reference external" href="https://www.khronos.org/spir">the SPIR
+specification</a>. There are two flavors
+available for 32 and 64 bits.</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -target spir-unknown-unknown test.cl
+<span class="gp">$</span> clang -target spir64-unknown-unknown test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>All known OpenCL extensions are supported in the SPIR targets. Clang will
+generate SPIR v1.2 compatible IR for OpenCL versions up to 2.0 and SPIR v2.0
+for OpenCL v2.0.</p>
+</li>
+<li><p class="first">x86 is used by some implementations that are x86 compatible and currently
+remains for backwards compatibility (with older implementations prior to
+SPIR target support). For ânon-SPMDâ targets which cannot spawn multiple
+work-items on the fly using hardware, which covers practically all non-GPU
+devices such as CPUs and DSPs, additional processing is needed for the kernels
+to support multiple work-item execution. For this, a 3rd party toolchain,
+such as for example <a class="reference external" href="http://portablecl.org/">POCL</a>, can be used.</p>
+<p>This target does not support multiple memory segments and, therefore, the fake
+address space map can be added using the <a class="reference internal" href="#opencl-fake-address-space-map"><span class="std std-ref">-ffake-address-space-map</span></a> flag.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="opencl-header">
+<span id="id7"></span><h3><a class="toc-backref" href="#id70">OpenCL Header</a><a class="headerlink" href="#opencl-header" title="Permalink to this headline">¶</a></h3>
+<p>By default Clang will not include standard headers and therefore OpenCL builtin
+functions and some types (i.e. vectors) are unknown. The default CL header is,
+however, provided in the Clang installation and can be enabled by passing the
+<code class="docutils literal notranslate"><span class="pre">-finclude-default-header</span></code> flag to the Clang frontend.</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">"bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}"</span> > test.cl
+<span class="gp">$</span> clang -Xclang -finclude-default-header -cl-std<span class="o">=</span>CL2.0 test.cl
+</pre></div>
+</div>
+</div></blockquote>
+<p>Because the header is very large and long to parse, PCH (<a class="reference internal" href="PCHInternals.html"><span class="doc">Precompiled Header and Modules Internals</span></a>)
+and modules (<a class="reference internal" href="Modules.html"><span class="doc">Modules</span></a>) are used internally to improve the compilation
+speed.</p>
+<p>To enable modules for OpenCL:</p>
+<blockquote>
+<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -target spir-unknown-unknown -c -emit-llvm -Xclang -finclude-default-header -fmodules -fimplicit-module-maps -fmodules-cache-path<span class="o">=</span><path to the generated module> test.cl
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="opencl-extensions">
+<h3><a class="toc-backref" href="#id71">OpenCL Extensions</a><a class="headerlink" href="#opencl-extensions" title="Permalink to this headline">¶</a></h3>
+<p>All of the <code class="docutils literal notranslate"><span class="pre">cl_khr_*</span></code> extensions from <a class="reference external" href="https://www.khronos.org/registry/OpenCL/sdk/2.0/docs/man/xhtml/EXTENSION.html">the official OpenCL specification</a>
+up to and including version 2.0 are available and set per target depending on the
+support available in the specific architecture.</p>
+<p>It is possible to alter the default extensions setting per target using
+<code class="docutils literal notranslate"><span class="pre">-cl-ext</span></code> flag. (See <a class="reference internal" href="#opencl-cl-ext"><span class="std std-ref">flags description</span></a> for more details).</p>
+<p>Vendor extensions can be added flexibly by declaring the list of types and
+functions associated with each extensions enclosed within the following
+compiler pragma directives:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma OPENCL EXTENSION the_new_extension_name : begin</span>
+<span class="c1">// declare types and functions associated with the extension here</span>
+<span class="cp">#pragma OPENCL EXTENSION the_new_extension_name : end</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>For example, parsing the following code adds <code class="docutils literal notranslate"><span class="pre">my_t</span></code> type and <code class="docutils literal notranslate"><span class="pre">my_func</span></code>
+function to the custom <code class="docutils literal notranslate"><span class="pre">my_ext</span></code> extension.</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#pragma OPENCL EXTENSION my_ext : begin</span>
+<span class="k">typedef</span> <span class="k">struct</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="n">my_t</span><span class="p">;</span>
+<span class="kt">void</span> <span class="nf">my_func</span><span class="p">(</span><span class="n">my_t</span><span class="p">);</span>
+<span class="cp">#pragma OPENCL EXTENSION my_ext : end</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Declaring the same types in different vendor extensions is disallowed.</p>
+</div>
+<div class="section" id="opencl-metadata">
+<h3><a class="toc-backref" href="#id72">OpenCL Metadata</a><a class="headerlink" href="#opencl-metadata" title="Permalink to this headline">¶</a></h3>
+<p>Clang uses metadata to provide additional OpenCL semantics in IR needed for
+backends and OpenCL runtime.</p>
+<p>Each kernel will have function metadata attached to it, specifying the arguments.
+Kernel argument metadata is used to provide source level information for querying
+at runtime, for example using the <a class="reference external" href="https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167">clGetKernelArgInfo</a>
+call.</p>
+<p>Note that <code class="docutils literal notranslate"><span class="pre">-cl-kernel-arg-info</span></code> enables more information about the original CL
+code to be added e.g. kernel parameter names will appear in the OpenCL metadata
+along with other information.</p>
+<p>The IDs used to encode the OpenCLâs logical address spaces in the argument info
+metadata follows the SPIR address space mapping as defined in the SPIR
+specification <a class="reference external" href="https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18">section 2.2</a></p>
+</div>
+<div class="section" id="opencl-specific-attributes">
+<h3><a class="toc-backref" href="#id73">OpenCL-Specific Attributes</a><a class="headerlink" href="#opencl-specific-attributes" title="Permalink to this headline">¶</a></h3>
+<p>OpenCL support in Clang contains a set of attribute taken directly from the
+specification as well as additional attributes.</p>
+<p>See also <a class="reference internal" href="AttributeReference.html"><span class="doc">Attributes in Clang</span></a>.</p>
+<div class="section" id="nosvm">
+<h4><a class="toc-backref" href="#id74">nosvm</a><a class="headerlink" href="#nosvm" title="Permalink to this headline">¶</a></h4>
+<p>Clang supports this attribute to comply to OpenCL v2.0 conformance, but it
+does not have any effect on the IR. For more details reffer to the specification
+<a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#49">section 6.7.2</a></p>
+</div>
+<div class="section" id="opencl-unroll-hint">
+<h4><a class="toc-backref" href="#id75">opencl_unroll_hint</a><a class="headerlink" href="#opencl-unroll-hint" title="Permalink to this headline">¶</a></h4>
+<p>The implementation of this feature mirrors the unroll hint for C.
+More details on the syntax can be found in the specification
+<a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#61">section 6.11.5</a></p>
+</div>
+<div class="section" id="convergent">
+<h4><a class="toc-backref" href="#id76">convergent</a><a class="headerlink" href="#convergent" title="Permalink to this headline">¶</a></h4>
+<p>To make sure no invalid optimizations occur for single program multiple data
+(SPMD) / single instruction multiple thread (SIMT) Clang provides attributes that
+can be used for special functions that have cross work item semantics.
+An example is the subgroup operations such as <a class="reference external" href="https://www.khronos.org/registry/cl/extensions/intel/cl_intel_subgroups.txt">intel_sub_group_shuffle</a></p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// Define custom my_sub_group_shuffle(data, c)</span>
+<span class="c1">// that makes use of intel_sub_group_shuffle</span>
+<span class="n">r1</span> <span class="o">=</span> <span class="p">...</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">r0</span><span class="p">)</span> <span class="n">r1</span> <span class="o">=</span> <span class="n">computeA</span><span class="p">();</span>
+<span class="c1">// Shuffle data from r1 into r3</span>
+<span class="c1">// of threads id r2.</span>
+<span class="n">r3</span> <span class="o">=</span> <span class="n">my_sub_group_shuffle</span><span class="p">(</span><span class="n">r1</span><span class="p">,</span> <span class="n">r2</span><span class="p">);</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">r0</span><span class="p">)</span> <span class="n">r3</span> <span class="o">=</span> <span class="n">computeB</span><span class="p">();</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>with non-SPMD semantics this is optimized to the following equivalent code:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">r1</span> <span class="o">=</span> <span class="p">...</span>
+<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">r0</span><span class="p">)</span>
+ <span class="c1">// Incorrect functionality! The data in r1</span>
+ <span class="c1">// have not been computed by all threads yet.</span>
+ <span class="n">r3</span> <span class="o">=</span> <span class="n">my_sub_group_shuffle</span><span class="p">(</span><span class="n">r1</span><span class="p">,</span> <span class="n">r2</span><span class="p">);</span>
+<span class="k">else</span> <span class="p">{</span>
+ <span class="n">r1</span> <span class="o">=</span> <span class="n">computeA</span><span class="p">();</span>
+ <span class="n">r3</span> <span class="o">=</span> <span class="n">my_sub_group_shuffle</span><span class="p">(</span><span class="n">r1</span><span class="p">,</span> <span class="n">r2</span><span class="p">);</span>
+ <span class="n">r3</span> <span class="o">=</span> <span class="n">computeB</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Declaring the function <code class="docutils literal notranslate"><span class="pre">my_sub_group_shuffle</span></code> with the convergent attribute
+would prevent this:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">my_sub_group_shuffle</span><span class="p">()</span> <span class="n">__attribute__</span><span class="p">((</span><span class="n">convergent</span><span class="p">));</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Using <code class="docutils literal notranslate"><span class="pre">convergent</span></code> guarantees correct execution by keeping CFG equivalence
+wrt operations marked as <code class="docutils literal notranslate"><span class="pre">convergent</span></code>. CFG <code class="docutils literal notranslate"><span class="pre">G´</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">G</span></code> wrt
+node <code class="docutils literal notranslate"><span class="pre">Ni</span></code> : <code class="docutils literal notranslate"><span class="pre">iff</span> <span class="pre">â</span> <span class="pre">Nj</span> <span class="pre">(iâ j)</span></code> domination and post-domination relations with
+respect to <code class="docutils literal notranslate"><span class="pre">Ni</span></code> remain the same in both <code class="docutils literal notranslate"><span class="pre">G</span></code> and <code class="docutils literal notranslate"><span class="pre">G´</span></code>.</p>
+</div>
+<div class="section" id="noduplicate">
+<h4><a class="toc-backref" href="#id77">noduplicate</a><a class="headerlink" href="#noduplicate" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">noduplicate</span></code> is more restrictive with respect to optimizations than
+<code class="docutils literal notranslate"><span class="pre">convergent</span></code> because a convergent function only preserves CFG equivalence.
+This allows some optimizations to happen as long as the control flow remains
+unmodified.</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">for</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="n">i</span><span class="o"><</span><span class="mi">4</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span>
+ <span class="n">my_sub_group_shuffle</span><span class="p">()</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>can be modified to:</p>
+<blockquote>
+<div><div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+<span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+<span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+<span class="n">my_sub_group_shuffle</span><span class="p">();</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>while using <code class="docutils literal notranslate"><span class="pre">noduplicate</span></code> would disallow this. Also <code class="docutils literal notranslate"><span class="pre">noduplicate</span></code> doesnât
+have the same safe semantics of CFG as <code class="docutils literal notranslate"><span class="pre">convergent</span></code> and can cause changes in
+CFG that modify semantics of the original program.</p>
+<p><code class="docutils literal notranslate"><span class="pre">noduplicate</span></code> is kept for backwards compatibility only and it considered to be
+deprecated for future uses.</p>
+</div>
+<div class="section" id="address-space">
+<span id="opencl-addrsp"></span><h4><a class="toc-backref" href="#id78">address_space</a><a class="headerlink" href="#address-space" title="Permalink to this headline">¶</a></h4>
+<p>Clang has arbitrary address space support using the <code class="docutils literal notranslate"><span class="pre">address_space(N)</span></code>
+attribute, where <code class="docutils literal notranslate"><span class="pre">N</span></code> is an integer number in the range <code class="docutils literal notranslate"><span class="pre">0</span></code> to <code class="docutils literal notranslate"><span class="pre">16777215</span></code>
+(<code class="docutils literal notranslate"><span class="pre">0xffffffu</span></code>).</p>
+<p>An OpenCL implementation provides a list of standard address spaces using
+keywords: <code class="docutils literal notranslate"><span class="pre">private</span></code>, <code class="docutils literal notranslate"><span class="pre">local</span></code>, <code class="docutils literal notranslate"><span class="pre">global</span></code>, and <code class="docutils literal notranslate"><span class="pre">generic</span></code>. In the AST and
+in the IR local, global, or generic will be represented by the address space
+attribute with the corresponding unique number. Note that private does not have
+any corresponding attribute added and, therefore, is represented by the absence
+of an address space number. The specific IDs for an address space do not have to
+match between the AST and the IR. Typically in the AST address space numbers
+represent logical segments while in the IR they represent physical segments.
+Therefore, machines with flat memory segments can map all AST address space
+numbers to the same physical segment ID or skip address space attribute
+completely while generating the IR. However, if the address space information
+is needed by the IR passes e.g. to improve alias analysis, it is recommended
+to keep it and only lower to reflect physical memory segments in the late
+machine passes.</p>
+</div>
+</div>
+<div class="section" id="opencl-builtins">
+<h3><a class="toc-backref" href="#id79">OpenCL builtins</a><a class="headerlink" href="#opencl-builtins" title="Permalink to this headline">¶</a></h3>
+<p>There are some standard OpenCL functions that are implemented as Clang builtins:</p>
+<ul class="simple">
+<li>All pipe functions from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160">section 6.13.16.2/6.13.16.3</a> of
+the OpenCL v2.0 kernel language specification. `</li>
+<li>Address space qualifier conversion functions <code class="docutils literal notranslate"><span class="pre">to_global</span></code>/<code class="docutils literal notranslate"><span class="pre">to_local</span></code>/<code class="docutils literal notranslate"><span class="pre">to_private</span></code>
+from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101">section 6.13.9</a>.</li>
+<li>All the <code class="docutils literal notranslate"><span class="pre">enqueue_kernel</span></code> functions from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164">section 6.13.17.1</a> and
+enqueue query functions from <a class="reference external" href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171">section 6.13.17.5</a>.</li>
+</ul>
+</div>
+<div class="section" id="c-for-opencl">
+<span id="opencl-cpp"></span><h3><a class="toc-backref" href="#id80">C++ for OpenCL</a><a class="headerlink" href="#c-for-opencl" title="Permalink to this headline">¶</a></h3>
+<p>Starting from clang 9 kernel code can contain C++17 features: classes, templates,
+function overloading, type deduction, etc. Please note that this is not an
+implementation of <a class="reference external" href="https://www.khronos.org/registry/OpenCL/specs/2.2/pdf/OpenCL_Cxx.pdf">OpenCL C++</a> and
+there is no plan to support it in clang in any new releases in the near future.</p>
+<p>For detailed information about restrictions to allowed C++ features please
+refer to <a class="reference internal" href="LanguageExtensions.html"><span class="doc">Clang Language Extensions</span></a>.</p>
+<p>Since C++ features are to be used on top of OpenCL C functionality, all existing
+restrictions from OpenCL C v2.0 will inherently apply. All OpenCL C builtin types
+and function libraries are supported and can be used in this mode.</p>
+<p>To enable the C++ for OpenCL mode, pass one of following command line options when
+compiling <code class="docutils literal notranslate"><span class="pre">.cl</span></code> file <code class="docutils literal notranslate"><span class="pre">-cl-std=clc++</span></code>, <code class="docutils literal notranslate"><span class="pre">-cl-std=CLC++</span></code>, <code class="docutils literal notranslate"><span class="pre">-std=clc++</span></code> or
+<code class="docutils literal notranslate"><span class="pre">-std=CLC++</span></code>.</p>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">template</span><span class="o"><</span><span class="k">class</span> <span class="nc">T</span><span class="o">></span> <span class="n">T</span> <span class="n">add</span><span class="p">(</span> <span class="n">T</span> <span class="n">x</span><span class="p">,</span> <span class="n">T</span> <span class="n">y</span> <span class="p">)</span>
+<span class="p">{</span>
+ <span class="k">return</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">__kernel</span> <span class="kt">void</span> <span class="n">test</span><span class="p">(</span> <span class="n">__global</span> <span class="kt">float</span><span class="o">*</span> <span class="n">a</span><span class="p">,</span> <span class="n">__global</span> <span class="kt">float</span><span class="o">*</span> <span class="n">b</span><span class="p">)</span>
+<span class="p">{</span>
+ <span class="k">auto</span> <span class="n">index</span> <span class="o">=</span> <span class="n">get_global_id</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="n">a</span><span class="p">[</span><span class="n">index</span><span class="p">]</span> <span class="o">=</span> <span class="n">add</span><span class="p">(</span><span class="n">b</span><span class="p">[</span><span class="n">index</span><span class="p">],</span> <span class="n">b</span><span class="p">[</span><span class="n">index</span><span class="o">+</span><span class="mi">1</span><span class="p">]);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">clang -cl-std=clc++ test.cl</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="target-specific-features-and-limitations">
+<span id="target-features"></span><h2><a class="toc-backref" href="#id81">Target-Specific Features and Limitations</a><a class="headerlink" href="#target-specific-features-and-limitations" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="cpu-architectures-features-and-limitations">
+<h3><a class="toc-backref" href="#id82">CPU Architectures Features and Limitations</a><a class="headerlink" href="#cpu-architectures-features-and-limitations" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="x86">
+<h4><a class="toc-backref" href="#id83">X86</a><a class="headerlink" href="#x86" title="Permalink to this headline">¶</a></h4>
+<p>The support for X86 (both 32-bit and 64-bit) is considered stable on
+Darwin (macOS), Linux, FreeBSD, and Dragonfly BSD: it has been tested
+to correctly compile many large C, C++, Objective-C, and Objective-C++
+codebases.</p>
+<p>On <code class="docutils literal notranslate"><span class="pre">x86_64-mingw32</span></code>, passing i128(by value) is incompatible with the
+Microsoft x64 calling convention. You might need to tweak
+<code class="docutils literal notranslate"><span class="pre">WinX86_64ABIInfo::classify()</span></code> in lib/CodeGen/TargetInfo.cpp.</p>
+<p>For the X86 target, clang supports the <cite>-m16</cite> command line
+argument which enables 16-bit code output. This is broadly similar to
+using <code class="docutils literal notranslate"><span class="pre">asm(".code16gcc")</span></code> with the GNU toolchain. The generated code
+and the ABI remains 32-bit but the assembler emits instructions
+appropriate for a CPU running in 16-bit mode, with address-size and
+operand-size prefixes to enable 32-bit addressing and operations.</p>
+</div>
+<div class="section" id="arm">
+<h4><a class="toc-backref" href="#id84">ARM</a><a class="headerlink" href="#arm" title="Permalink to this headline">¶</a></h4>
+<p>The support for ARM (specifically ARMv6 and ARMv7) is considered stable
+on Darwin (iOS): it has been tested to correctly compile many large C,
+C++, Objective-C, and Objective-C++ codebases. Clang only supports a
+limited number of ARM architectures. It does not yet fully support
+ARMv5, for example.</p>
+</div>
+<div class="section" id="powerpc">
+<h4><a class="toc-backref" href="#id85">PowerPC</a><a class="headerlink" href="#powerpc" title="Permalink to this headline">¶</a></h4>
+<p>The support for PowerPC (especially PowerPC64) is considered stable
+on Linux and FreeBSD: it has been tested to correctly compile many
+large C and C++ codebases. PowerPC (32bit) is still missing certain
+features (e.g. PIC code on ELF platforms).</p>
+</div>
+<div class="section" id="other-platforms">
+<h4><a class="toc-backref" href="#id86">Other platforms</a><a class="headerlink" href="#other-platforms" title="Permalink to this headline">¶</a></h4>
+<p>clang currently contains some support for other architectures (e.g. Sparc);
+however, significant pieces of code generation are still missing, and they
+havenât undergone significant testing.</p>
+<p>clang contains limited support for the MSP430 embedded processor, but
+both the clang support and the LLVM backend support are highly
+experimental.</p>
+<p>Other platforms are completely unsupported at the moment. Adding the
+minimal support needed for parsing and semantic analysis on a new
+platform is quite easy; see <code class="docutils literal notranslate"><span class="pre">lib/Basic/Targets.cpp</span></code> in the clang source
+tree. This level of support is also sufficient for conversion to LLVM IR
+for simple programs. Proper support for conversion to LLVM IR requires
+adding code to <code class="docutils literal notranslate"><span class="pre">lib/CodeGen/CGCall.cpp</span></code> at the moment; this is likely to
+change soon, though. Generating assembly requires a suitable LLVM
+backend.</p>
+</div>
+</div>
+<div class="section" id="operating-system-features-and-limitations">
+<h3><a class="toc-backref" href="#id87">Operating System Features and Limitations</a><a class="headerlink" href="#operating-system-features-and-limitations" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="darwin-macos">
+<h4><a class="toc-backref" href="#id88">Darwin (macOS)</a><a class="headerlink" href="#darwin-macos" title="Permalink to this headline">¶</a></h4>
+<p>Thread Sanitizer is not supported.</p>
+</div>
+<div class="section" id="windows">
+<h4><a class="toc-backref" href="#id89">Windows</a><a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h4>
+<p>Clang has experimental support for targeting âCygmingâ (Cygwin / MinGW)
+platforms.</p>
+<p>See also <a class="reference internal" href="#c-ms"><span class="std std-ref">Microsoft Extensions</span></a>.</p>
+<div class="section" id="cygwin">
+<h5><a class="toc-backref" href="#id90">Cygwin</a><a class="headerlink" href="#cygwin" title="Permalink to this headline">¶</a></h5>
+<p>Clang works on Cygwin-1.7.</p>
+</div>
+<div class="section" id="mingw32">
+<h5><a class="toc-backref" href="#id91">MinGW32</a><a class="headerlink" href="#mingw32" title="Permalink to this headline">¶</a></h5>
+<p>Clang works on some mingw32 distributions. Clang assumes directories as
+below;</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">C:/mingw/include</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">C:/mingw/lib</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++</span></code></li>
+</ul>
+<p>On MSYS, a few tests might fail.</p>
+</div>
+<div class="section" id="mingw-w64">
+<h5><a class="toc-backref" href="#id92">MinGW-w64</a><a class="headerlink" href="#mingw-w64" title="Permalink to this headline">¶</a></h5>
+<p>For 32-bit (i686-w64-mingw32), and 64-bit (x86_64-w64-mingw32), Clang
+assumes as below;</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">GCC</span> <span class="pre">versions</span> <span class="pre">4.5.0</span> <span class="pre">to</span> <span class="pre">4.5.3,</span> <span class="pre">4.6.0</span> <span class="pre">to</span> <span class="pre">4.6.2,</span> <span class="pre">or</span> <span class="pre">4.7.0</span> <span class="pre">(for</span> <span class="pre">the</span> <span class="pre">C++</span> <span class="pre">header</span> <span class="pre">search</span> <span class="pre">path)</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">some_directory/bin/gcc.exe</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">some_directory/bin/clang.exe</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">some_directory/bin/clang++.exe</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">some_directory/bin/../include/c++/GCC_version</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">some_directory/bin/../include/c++/GCC_version/backward</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">some_directory/bin/../x86_64-w64-mingw32/include</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">some_directory/bin/../i686-w64-mingw32/include</span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre">some_directory/bin/../include</span></code></li>
+</ul>
+<p>This directory layout is standard for any toolchain you will find on the
+official <a class="reference external" href="http://mingw-w64.sourceforge.net">MinGW-w64 website</a>.</p>
+<p>Clang expects the GCC executable âgcc.exeâ compiled for
+<code class="docutils literal notranslate"><span class="pre">i686-w64-mingw32</span></code> (or <code class="docutils literal notranslate"><span class="pre">x86_64-w64-mingw32</span></code>) to be present on PATH.</p>
+<p><a class="reference external" href="https://bugs.llvm.org/show_bug.cgi?id=9072">Some tests might fail</a> on
+<code class="docutils literal notranslate"><span class="pre">x86_64-w64-mingw32</span></code>.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="clang-cl">
+<span id="id8"></span><h2><a class="toc-backref" href="#id93">clang-cl</a><a class="headerlink" href="#clang-cl" title="Permalink to this headline">¶</a></h2>
+<p>clang-cl is an alternative command-line interface to Clang, designed for
+compatibility with the Visual C++ compiler, cl.exe.</p>
+<p>To enable clang-cl to find system headers, libraries, and the linker when run
+from the command-line, it should be executed inside a Visual Studio Native Tools
+Command Prompt or a regular Command Prompt where the environment has been set
+up using e.g. <a class="reference external" href="https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx">vcvarsall.bat</a>.</p>
+<p>clang-cl can also be used from inside Visual Studio by selecting the LLVM
+Platform Toolset. The toolset is not part of the installer, but may be installed
+separately from the
+<a class="reference external" href="https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.llvm-toolchain">Visual Studio Marketplace</a>.
+To use the toolset, select a project in Solution Explorer, open its Property
+Page (Alt+F7), and in the âGeneralâ section of âConfiguration Propertiesâ
+change âPlatform Toolsetâ to LLVM. Doing so enables an additional Property
+Page for selecting the clang-cl executable to use for builds.</p>
+<p>To use the toolset with MSBuild directly, invoke it with e.g.
+<code class="docutils literal notranslate"><span class="pre">/p:PlatformToolset=LLVM</span></code>. This allows trying out the clang-cl toolchain
+without modifying your project files.</p>
+<p>Itâs also possible to point MSBuild at clang-cl without changing toolset by
+passing <code class="docutils literal notranslate"><span class="pre">/p:CLToolPath=c:\llvm\bin</span> <span class="pre">/p:CLToolExe=clang-cl.exe</span></code>.</p>
+<p>When using CMake and the Visual Studio generators, the toolset can be set with the <code class="docutils literal notranslate"><span class="pre">-T</span></code> flag:</p>
+<blockquote>
+<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cmake</span> <span class="o">-</span><span class="n">G</span><span class="s2">"Visual Studio 15 2017"</span> <span class="o">-</span><span class="n">T</span> <span class="n">LLVM</span> <span class="o">..</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>When using CMake with the Ninja generator, set the <code class="docutils literal notranslate"><span class="pre">CMAKE_C_COMPILER</span></code> and
+<code class="docutils literal notranslate"><span class="pre">CMAKE_CXX_COMPILER</span></code> variables to clang-cl:</p>
+<blockquote>
+<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cmake</span> <span class="o">-</span><span class="n">GNinja</span> <span class="o">-</span><span class="n">DCMAKE_C_COMPILER</span><span class="o">=</span><span class="s2">"c:/Program Files (x86)/LLVM/bin/clang-cl.exe"</span>
+ <span class="o">-</span><span class="n">DCMAKE_CXX_COMPILER</span><span class="o">=</span><span class="s2">"c:/Program Files (x86)/LLVM/bin/clang-cl.exe"</span> <span class="o">..</span>
+</pre></div>
+</div>
+</div></blockquote>
+<div class="section" id="id9">
+<h3><a class="toc-backref" href="#id94">Command-Line Options</a><a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h3>
+<p>To be compatible with cl.exe, clang-cl supports most of the same command-line
+options. Those options can start with either <code class="docutils literal notranslate"><span class="pre">/</span></code> or <code class="docutils literal notranslate"><span class="pre">-</span></code>. It also supports
+some of Clangâs core options, such as the <code class="docutils literal notranslate"><span class="pre">-W</span></code> options.</p>
+<p>Options that are known to clang-cl, but not currently supported, are ignored
+with a warning. For example:</p>
+<blockquote>
+<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">clang</span><span class="o">-</span><span class="n">cl</span><span class="o">.</span><span class="n">exe</span><span class="p">:</span> <span class="n">warning</span><span class="p">:</span> <span class="n">argument</span> <span class="n">unused</span> <span class="n">during</span> <span class="n">compilation</span><span class="p">:</span> <span class="s1">'/AI'</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>To suppress warnings about unused arguments, use the <code class="docutils literal notranslate"><span class="pre">-Qunused-arguments</span></code> option.</p>
+<p>Options that are not known to clang-cl will be ignored by default. Use the
+<code class="docutils literal notranslate"><span class="pre">-Werror=unknown-argument</span></code> option in order to treat them as errors. If these
+options are spelled with a leading <code class="docutils literal notranslate"><span class="pre">/</span></code>, they will be mistaken for a filename:</p>
+<blockquote>
+<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">clang</span><span class="o">-</span><span class="n">cl</span><span class="o">.</span><span class="n">exe</span><span class="p">:</span> <span class="n">error</span><span class="p">:</span> <span class="n">no</span> <span class="n">such</span> <span class="n">file</span> <span class="ow">or</span> <span class="n">directory</span><span class="p">:</span> <span class="s1">'/foobar'</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>Please <a class="reference external" href="https://bugs.llvm.org/enter_bug.cgi?product=clang&component=Driver">file a bug</a>
+for any valid cl.exe flags that clang-cl does not understand.</p>
+<p>Execute <code class="docutils literal notranslate"><span class="pre">clang-cl</span> <span class="pre">/?</span></code> to see a list of supported options:</p>
+<blockquote>
+<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span>CL.EXE COMPATIBILITY OPTIONS:
+ /? Display available options
+ /arch:<value> Set architecture for code generation
+ /Brepro- Write current time into COFF output (default)
+ /Brepro Do not write current time into COFF output (breaks link.exe /incremental)
+ /clang:<arg> Pass <arg> to the clang driver
+ /C Do not discard comments when preprocessing
+ /c Compile only
+ /d1PP Retain macro definitions in /E mode
+ /d1reportAllClassLayout Dump record layout information
+ /diagnostics:caret Enable caret and column diagnostics (default)
+ /diagnostics:classic Disable column and caret diagnostics
+ /diagnostics:column Disable caret diagnostics but keep column info
+ /D <macro[=value]> Define macro
+ /EH<value> Set exception handling model
+ /EP Disable linemarker output and preprocess to stdout
+ /execution-charset:<value>
+ Set runtime encoding, supports only UTF-8
+ /E Preprocess to stdout
+ /fallback Fall back to cl.exe if clang-cl fails to compile
+ /FA Output assembly code file during compilation
+ /Fa<file or dir/> Set assembly output file name (with /FA)
+ /Fe<file or dir/> Set output executable file name
+ /FI <value> Include file before parsing
+ /Fi<file> Set preprocess output file name (with /P)
+ /Fo<file or dir/> Set output object file (with /c)
+ /fp:except-
+ /fp:except
+ /fp:fast
+ /fp:precise
+ /fp:strict
+ /Fp<file> Set pch file name (with /Yc and /Yu)
+ /GA Assume thread-local variables are defined in the executable
+ /Gd Set __cdecl as a default calling convention
+ /GF- Disable string pooling
+ /GF Enable string pooling (default)
+ /GR- Do not emit RTTI data
+ /Gregcall Set __regcall as a default calling convention
+ /GR Emit RTTI data (default)
+ /Gr Set __fastcall as a default calling convention
+ /GS- Disable buffer security check
+ /GS Enable buffer security check (default)
+ /Gs Use stack probes (default)
+ /Gs<value> Set stack probe size (default 4096)
+ /guard:<value> Enable Control Flow Guard with /guard:cf,
+ or only the table with /guard:cf,nochecks
+ /Gv Set __vectorcall as a default calling convention
+ /Gw- Do not put each data item in its own section (default)
+ /Gw Put each data item in its own section
+ /GX- Deprecated (like not passing /EH)
+ /GX Deprecated; use /EHsc
+ /Gy- Do not put each function in its own section (default)
+ /Gy Put each function in its own section
+ /Gz Set __stdcall as a default calling convention
+ /help Display available options
+ /imsvc <dir> Add <dir> to system include search path, as if in %INCLUDE%
+ /I <dir> Add directory to include search path
+ /J Make char type unsigned
+ /LDd Create debug DLL
+ /LD Create DLL
+ /link <options> Forward options to the linker
+ /MDd Use DLL debug run-time
+ /MD Use DLL run-time
+ /MTd Use static debug run-time
+ /MT Use static run-time
+ /O1 Optimize for size (like /Og /Os /Oy /Ob2 /GF /Gy)
+ /O2 Optimize for speed (like /Og /Oi /Ot /Oy /Ob2 /GF /Gy)
+ /Ob0 Disable function inlining
+ /Ob1 Only inline functions explicitly or implicitly marked inline
+ /Ob2 Inline functions as deemed beneficial by the compiler
+ /Od Disable optimization
+ /Og No effect
+ /Oi- Disable use of builtin functions
+ /Oi Enable use of builtin functions
+ /Os Optimize for size
+ /Ot Optimize for speed
+ /Ox Deprecated (like /Og /Oi /Ot /Oy /Ob2); use /O2
+ /Oy- Disable frame pointer omission (x86 only, default)
+ /Oy Enable frame pointer omission (x86 only)
+ /O<flags> Set multiple /O flags at once; e.g. '/O2y-' for '/O2 /Oy-'
+ /o <file or dir/> Deprecated (set output file name); use /Fe or /Fe
+ /P Preprocess to file
+ /Qvec- Disable the loop vectorization passes
+ /Qvec Enable the loop vectorization passes
+ /showFilenames- Do not print the name of each compiled file (default)
+ /showFilenames Print the name of each compiled file
+ /showIncludes Print info about included files to stderr
+ /source-charset:<value> Set source encoding, supports only UTF-8
+ /std:<value> Set C++ version (c++14,c++17,c++latest)
+ /TC Treat all source files as C
+ /Tc <file> Treat <file> as C source file
+ /TP Treat all source files as C++
+ /Tp <file> Treat <file> as C++ source file
+ /utf-8 Set source and runtime encoding to UTF-8 (default)
+ /U <macro> Undefine macro
+ /vd<value> Control vtordisp placement
+ /vmb Use a best-case representation method for member pointers
+ /vmg Use a most-general representation for member pointers
+ /vmm Set the default most-general representation to multiple inheritance
+ /vms Set the default most-general representation to single inheritance
+ /vmv Set the default most-general representation to virtual inheritance
+ /volatile:iso Volatile loads and stores have standard semantics
+ /volatile:ms Volatile loads and stores have acquire and release semantics
+ /W0 Disable all warnings
+ /W1 Enable -Wall
+ /W2 Enable -Wall
+ /W3 Enable -Wall
+ /W4 Enable -Wall and -Wextra
+ /Wall Enable -Weverything
+ /WX- Do not treat warnings as errors (default)
+ /WX Treat warnings as errors
+ /w Disable all warnings
+ /X Do not add %INCLUDE% to include search path
+ /Y- Disable precompiled headers, overrides /Yc and /Yu
+ /Yc<filename> Generate a pch file for all code up to and including <filename>
+ /Yu<filename> Load a pch file and use it instead of all code up to and including <filename>
+ /Z7 Enable CodeView debug information in object files
+ /Zc:alignedNew- Disable C++17 aligned allocation functions
+ /Zc:alignedNew Enable C++17 aligned allocation functions
+ /Zc:char8_t- Disable char8_t from c++2a
+ /Zc:char8_t Enable char8_t from C++2a
+ /Zc:dllexportInlines- Do not dllexport/dllimport inline member functions of dllexport/import classes
+ /Zc:dllexportInlines dllexport/dllimport inline member functions of dllexport/import classes (default)
+ /Zc:sizedDealloc- Disable C++14 sized global deallocation functions
+ /Zc:sizedDealloc Enable C++14 sized global deallocation functions
+ /Zc:strictStrings Treat string literals as const
+ /Zc:threadSafeInit- Disable thread-safe initialization of static variables
+ /Zc:threadSafeInit Enable thread-safe initialization of static variables
+ /Zc:trigraphs- Disable trigraphs (default)
+ /Zc:trigraphs Enable trigraphs
+ /Zc:twoPhase- Disable two-phase name lookup in templates (default)
+ /Zc:twoPhase Enable two-phase name lookup in templates
+ /Zd Emit debug line number tables only
+ /Zi Like /Z7
+ /Zl Do not let object file auto-link default libraries
+ /Zp Set default maximum struct packing alignment to 1
+ /Zp<value> Set default maximum struct packing alignment
+ /Zs Syntax-check only
+
+OPTIONS:
+ -### Print (but do not run) the commands to run for this compilation
+ --analyze Run the static analyzer
+ -faddrsig Emit an address-significance table
+ -fansi-escape-codes Use ANSI escape codes for diagnostics
+ -fblocks Enable the 'blocks' language feature
+ -fcf-protection=<value> Instrument control-flow architecture protection. Options: return, branch, full, none.
+ -fcf-protection Enable cf-protection in 'full' mode
+ -fcolor-diagnostics Use colors in diagnostics
+ -fcomplete-member-pointers
+ Require member pointer base types to be complete if they would be significant under the Microsoft ABI
+ -fcoverage-mapping Generate coverage mapping to enable code coverage analysis
+ -fcs-profile-generate=<directory>
+ Generate instrumented code to collect context sensitive
+ execution counts into <directory>/default.profraw
+ (overridden by LLVM_PROFILE_FILE env var)
+ -fcs-profile-generate Generate instrumented code to collect context sensitive
+ execution counts into default.profraw
+ (overridden by LLVM_PROFILE_FILE env var)
+ -fdebug-compilation-dir <value>
+ The compilation directory to embed in the debug info.
+ -fdebug-macro Emit macro debug information
+ -fdelayed-template-parsing
+ Parse templated function definitions at the end of the translation unit
+ -fdiagnostics-absolute-paths
+ Print absolute paths in diagnostics
+ -fdiagnostics-parseable-fixits
+ Print fix-its in machine parseable form
+ -flto=<value> Set LTO mode to either 'full' or 'thin'
+ -flto Enable LTO in 'full' mode
+ -fmerge-all-constants Allow merging of constants
+ -fms-compatibility-version=<value>
+ Dot-separated value representing the Microsoft compiler version
+ number to report in _MSC_VER (0 = don't define it (default))
+ -fms-compatibility Enable full Microsoft Visual C++ compatibility
+ -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler
+ -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER
+ (0 = don't define it (default))
+ -fno-addrsig Don't emit an address-significance table
+ -fno-builtin-<value> Disable implicit builtin knowledge of a specific function
+ -fno-builtin Disable implicit builtin knowledge of functions
+ -fno-complete-member-pointers
+ Do not require member pointer base types to be complete if they would be significant under the Microsoft ABI
+ -fno-coverage-mapping Disable code coverage analysis
+ -fno-crash-diagnostics Disable auto-generation of preprocessed source files and a script for reproduction during a clang crash
+ -fno-debug-macro Do not emit macro debug information
+ -fno-delayed-template-parsing
+ Disable delayed template parsing
+ -fno-profile-generate Disable generation of profile instrumentation.
+ -fno-profile-instr-generate
+ Disable generation of profile instrumentation.
+ -fno-profile-instr-use Disable using instrumentation data for profile-guided optimization
+ -fno-sanitize-address-poison-custom-array-cookie
+ Disable poisoning array cookies when using custom operator new[] in AddressSanitizer
+ -fno-sanitize-address-use-after-scope
+ Disable use-after-scope detection in AddressSanitizer
+ -fno-sanitize-address-use-odr-indicator
+ Disable ODR indicator globals
+ -fno-sanitize-blacklist Don't use blacklist file for sanitizers
+ -fno-sanitize-cfi-cross-dso
+ Disable control flow integrity (CFI) checks for cross-DSO calls.
+ -fno-sanitize-coverage=<value>
+ Disable specified features of coverage instrumentation for Sanitizers
+ -fno-sanitize-memory-track-origins
+ Disable origins tracking in MemorySanitizer
+ -fno-sanitize-memory-use-after-dtor
+ Disable use-after-destroy detection in MemorySanitizer
+ -fno-sanitize-recover=<value>
+ Disable recovery for specified sanitizers
+ -fno-sanitize-stats Disable sanitizer statistics gathering.
+ -fno-sanitize-thread-atomics
+ Disable atomic operations instrumentation in ThreadSanitizer
+ -fno-sanitize-thread-func-entry-exit
+ Disable function entry/exit instrumentation in ThreadSanitizer
+ -fno-sanitize-thread-memory-access
+ Disable memory access instrumentation in ThreadSanitizer
+ -fno-sanitize-trap=<value>
+ Disable trapping for specified sanitizers
+ -fno-standalone-debug Limit debug information produced to reduce size of debug binary
+ -fobjc-runtime=<value> Specify the target Objective-C runtime kind and version
+ -forder-file-instrumentation
+ Generate instrumented code to collect order file into default.profraw
+ file (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
+ -fprofile-exclude-files=<value>
+ Instrument only functions from files where names don't match all the regexes separated by a semi-colon
+ -fprofile-filter-files=<value>
+ Instrument only functions from files where names match any regex separated by a semi-colon
+ -fprofile-generate=<directory>
+ Generate instrumented code to collect execution counts into
+ <directory>/default.profraw (overridden by LLVM_PROFILE_FILE env var)
+ -fprofile-generate Generate instrumented code to collect execution counts into
+ default.profraw (overridden by LLVM_PROFILE_FILE env var)
+ -fprofile-instr-generate=<file>
+ Generate instrumented code to collect execution counts into <file>
+ (overridden by LLVM_PROFILE_FILE env var)
+ -fprofile-instr-generate
+ Generate instrumented code to collect execution counts into default.profraw file
+ (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
+ -fprofile-instr-use=<value>
+ Use instrumentation data for profile-guided optimization
+ -fprofile-remapping-file=<file>
+ Use the remappings described in <file> to match the profile data against names in the program
+ -fsanitize-address-field-padding=<value>
+ Level of field padding for AddressSanitizer
+ -fsanitize-address-globals-dead-stripping
+ Enable linker dead stripping of globals in AddressSanitizer
+ -fsanitize-address-poison-custom-array-cookie
+ Enable poisoning array cookies when using custom operator new[] in AddressSanitizer
+ -fsanitize-address-use-after-scope
+ Enable use-after-scope detection in AddressSanitizer
+ -fsanitize-address-use-odr-indicator
+ Enable ODR indicator globals to avoid false ODR violation reports in partially sanitized programs at the cost of an increase in binary size
+ -fsanitize-blacklist=<value>
+ Path to blacklist file for sanitizers
+ -fsanitize-cfi-cross-dso
+ Enable control flow integrity (CFI) checks for cross-DSO calls.
+ -fsanitize-cfi-icall-generalize-pointers
+ Generalize pointers in CFI indirect call type signature checks
+ -fsanitize-coverage=<value>
+ Specify the type of coverage instrumentation for Sanitizers
+ -fsanitize-hwaddress-abi=<value>
+ Select the HWAddressSanitizer ABI to target (interceptor or platform, default interceptor)
+ -fsanitize-memory-track-origins=<value>
+ Enable origins tracking in MemorySanitizer
+ -fsanitize-memory-track-origins
+ Enable origins tracking in MemorySanitizer
+ -fsanitize-memory-use-after-dtor
+ Enable use-after-destroy detection in MemorySanitizer
+ -fsanitize-recover=<value>
+ Enable recovery for specified sanitizers
+ -fsanitize-stats Enable sanitizer statistics gathering.
+ -fsanitize-thread-atomics
+ Enable atomic operations instrumentation in ThreadSanitizer (default)
+ -fsanitize-thread-func-entry-exit
+ Enable function entry/exit instrumentation in ThreadSanitizer (default)
+ -fsanitize-thread-memory-access
+ Enable memory access instrumentation in ThreadSanitizer (default)
+ -fsanitize-trap=<value> Enable trapping for specified sanitizers
+ -fsanitize-undefined-strip-path-components=<number>
+ Strip (or keep only, if negative) a given number of path components when emitting check metadata.
+ -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious behavior. See user manual for available checks
+ -fsplit-lto-unit Enables splitting of the LTO unit.
+ -fstandalone-debug Emit full debug info for all types used by the program
+ -fthinlto-index=<value> Perform ThinLTO importing using provided function summary index
+ -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto
+ -gcodeview-ghash Emit type record hashes in a .debug$H section
+ -gcodeview Generate CodeView debug information
+ -gline-directives-only Emit debug line info directives only
+ -gline-tables-only Emit debug line number tables only
+ -miamcu Use Intel MCU ABI
+ -mllvm <value> Additional arguments to forward to LLVM's option processing
+ -nobuiltininc Disable builtin #include directories
+ -print-supported-cpus Print supported cpu models for the given target (if target is not specified, it will print the supported cpus for the default target)
+ -Qunused-arguments Don't emit warning for unused driver arguments
+ -R<remark> Enable the specified remark
+ --target=<value> Generate code for the given target
+ --version Print version information
+ -v Show commands to run and use verbose output
+ -W<warning> Enable the specified warning
+ -Xclang <arg> Pass <arg> to the clang compiler
+</pre></div>
+</div>
+</div></blockquote>
+<div class="section" id="the-clang-option">
+<h4><a class="toc-backref" href="#id95">The /clang: Option</a><a class="headerlink" href="#the-clang-option" title="Permalink to this headline">¶</a></h4>
+<p>When clang-cl is run with a set of <code class="docutils literal notranslate"><span class="pre">/clang:<arg></span></code> options, it will gather all
+of the <code class="docutils literal notranslate"><span class="pre"><arg></span></code> arguments and process them as if they were passed to the clang
+driver. This mechanism allows you to pass flags that are not exposed in the
+clang-cl options or flags that have a different meaning when passed to the clang
+driver. Regardless of where they appear in the command line, the <code class="docutils literal notranslate"><span class="pre">/clang:</span></code>
+arguments are treated as if they were passed at the end of the clang-cl command
+line.</p>
+</div>
+<div class="section" id="the-zc-dllexportinlines-option">
+<h4><a class="toc-backref" href="#id96">The /Zc:dllexportInlines- Option</a><a class="headerlink" href="#the-zc-dllexportinlines-option" title="Permalink to this headline">¶</a></h4>
+<p>This causes the class-level <cite>dllexport</cite> and <cite>dllimport</cite> attributes to not apply
+to inline member functions, as they otherwise would. For example, in the code
+below <cite>S::foo()</cite> would normally be defined and exported by the DLL, but when
+using the <code class="docutils literal notranslate"><span class="pre">/Zc:dllexportInlines-</span></code> flag it is not:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nf">__declspec</span><span class="p">(</span><span class="n">dllexport</span><span class="p">)</span> <span class="n">S</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This has the benefit that the compiler doesnât need to emit a definition of
+<cite>S::foo()</cite> in every translation unit where the declaration is included, as it
+would otherwise do to ensure thereâs a definition in the DLL even if itâs not
+used there. If the declaration occurs in a header file thatâs widely used, this
+can save significant compilation time and output size. It also reduces the
+number of functions exported by the DLL similarly to what
+<code class="docutils literal notranslate"><span class="pre">-fvisibility-inlines-hidden</span></code> does for shared objects on ELF and Mach-O.
+Since the function declaration comes with an inline definition, users of the
+library can use that definition directly instead of importing it from the DLL.</p>
+<p>Note that the Microsoft Visual C++ compiler does not support this option, and
+if code in a DLL is compiled with <code class="docutils literal notranslate"><span class="pre">/Zc:dllexportInlines-</span></code>, the code using the
+DLL must be compiled in the same way so that it doesnât attempt to dllimport
+the inline member functions. The reverse scenario should generally work though:
+a DLL compiled without this flag (such as a system library compiled with Visual
+C++) can be referenced from code compiled using the flag, meaning that the
+referencing code will use the inline definitions instead of importing them from
+the DLL.</p>
+<p>Also note that like when using <code class="docutils literal notranslate"><span class="pre">-fvisibility-inlines-hidden</span></code>, the address of
+<cite>S::foo()</cite> will be different inside and outside the DLL, breaking the C/C++
+standard requirement that functions have a unique address.</p>
+<p>The flag does not apply to explicit class template instantiation definitions or
+declarations, as those are typically used to explicitly provide a single
+definition in a DLL, (dllexported instantiation definition) or to signal that
+the definition is available elsewhere (dllimport instantiation declaration). It
+also doesnât apply to inline members with static local variables, to ensure
+that the same instance of the variable is used inside and outside the DLL.</p>
+<p>Using this flag can cause problems when inline functions that would otherwise
+be dllexported refer to internal symbols of a DLL. For example:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">internal</span><span class="p">();</span>
+
+<span class="k">struct</span> <span class="nf">__declspec</span><span class="p">(</span><span class="n">dllimport</span><span class="p">)</span> <span class="n">S</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span> <span class="n">internal</span><span class="p">();</span> <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Normally, references to <cite>S::foo()</cite> would use the definition in the DLL from
+which it was exported, and which presumably also has the definition of
+<cite>internal()</cite>. However, when using <code class="docutils literal notranslate"><span class="pre">/Zc:dllexportInlines-</span></code>, the inline
+definition of <cite>S::foo()</cite> is used directly, resulting in a link error since
+<cite>internal()</cite> is not available. Even worse, if there is an inline definition of
+<cite>internal()</cite> containing a static local variable, we will now refer to a
+different instance of that variable than in the DLL:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kr">inline</span> <span class="kt">int</span> <span class="nf">internal</span><span class="p">()</span> <span class="p">{</span> <span class="k">static</span> <span class="kt">int</span> <span class="n">x</span><span class="p">;</span> <span class="k">return</span> <span class="n">x</span><span class="o">++</span><span class="p">;</span> <span class="p">}</span>
+
+<span class="k">struct</span> <span class="nf">__declspec</span><span class="p">(</span><span class="n">dllimport</span><span class="p">)</span> <span class="n">S</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">internal</span><span class="p">();</span> <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This could lead to very subtle bugs. Using <code class="docutils literal notranslate"><span class="pre">-fvisibility-inlines-hidden</span></code> can
+lead to the same issue. To avoid it in this case, make <cite>S::foo()</cite> or
+<cite>internal()</cite> non-inline, or mark them <cite>dllimport/dllexport</cite> explicitly.</p>
+</div>
+<div class="section" id="the-fallback-option">
+<h4><a class="toc-backref" href="#id97">The /fallback Option</a><a class="headerlink" href="#the-fallback-option" title="Permalink to this headline">¶</a></h4>
+<p>When clang-cl is run with the <code class="docutils literal notranslate"><span class="pre">/fallback</span></code> option, it will first try to
+compile files itself. For any file that it fails to compile, it will fall back
+and try to compile the file by invoking cl.exe.</p>
+<p>This option is intended to be used as a temporary means to build projects where
+clang-cl cannot successfully compile all the files. clang-cl may fail to compile
+a file either because it cannot generate code for some C++ feature, or because
+it cannot parse some Microsoft language extension.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ <div class="bottomnav" role="navigation" aria-label="bottom navigation">
+
+ <p>
+ « <a href="ReleaseNotes.html">Clang 9.0.0 Release Notes</a>
+ ::
+ <a class="uplink" href="index.html">Contents</a>
+ ::
+ <a href="Toolchain.html">Assembling a Complete Toolchain</a> »
+ </p>
+
+ </div>
+
+ <div class="footer" role="contentinfo">
+ © Copyright 2007-2019, The Clang Team.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/tools/clang/docs/_images/DriverArchitecture.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/_images/DriverArchitecture.png?rev=372328&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/9.0.0/tools/clang/docs/_images/DriverArchitecture.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/9.0.0/tools/clang/docs/_images/PCHLayout.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/_images/PCHLayout.png?rev=372328&view=auto
==============================================================================
Binary file - no diff available.
Propchange: www-releases/trunk/9.0.0/tools/clang/docs/_images/PCHLayout.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: www-releases/trunk/9.0.0/tools/clang/docs/_sources/AddressSanitizer.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/_sources/AddressSanitizer.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/_sources/AddressSanitizer.rst.txt (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/_sources/AddressSanitizer.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,298 @@
+================
+AddressSanitizer
+================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+AddressSanitizer is a fast memory error detector. It consists of a compiler
+instrumentation module and a run-time library. The tool can detect the
+following types of bugs:
+
+* Out-of-bounds accesses to heap, stack and globals
+* Use-after-free
+* Use-after-return (runtime flag `ASAN_OPTIONS=detect_stack_use_after_return=1`)
+* Use-after-scope (clang flag `-fsanitize-address-use-after-scope`)
+* Double-free, invalid free
+* Memory leaks (experimental)
+
+Typical slowdown introduced by AddressSanitizer is **2x**.
+
+How to build
+============
+
+Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>`_.
+
+Usage
+=====
+
+Simply compile and link your program with ``-fsanitize=address`` flag. The
+AddressSanitizer run-time library should be linked to the final executable, so
+make sure to use ``clang`` (not ``ld``) for the final link step. When linking
+shared libraries, the AddressSanitizer run-time is not linked, so
+``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer). To
+get a reasonable performance add ``-O1`` or higher. To get nicer stack traces
+in error messages add ``-fno-omit-frame-pointer``. To get perfect stack traces
+you may need to disable inlining (just use ``-O1``) and tail call elimination
+(``-fno-optimize-sibling-calls``).
+
+.. code-block:: console
+
+ % cat example_UseAfterFree.cc
+ int main(int argc, char **argv) {
+ int *array = new int[100];
+ delete [] array;
+ return array[argc]; // BOOM
+ }
+
+ # Compile and link
+ % clang++ -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc
+
+or:
+
+.. code-block:: console
+
+ # Compile
+ % clang++ -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc
+ # Link
+ % clang++ -g -fsanitize=address example_UseAfterFree.o
+
+If a bug is detected, the program will print an error message to stderr and
+exit with a non-zero exit code. AddressSanitizer exits on the first detected error.
+This is by design:
+
+* This approach allows AddressSanitizer to produce faster and smaller generated code
+ (both by ~5%).
+* Fixing bugs becomes unavoidable. AddressSanitizer does not produce
+ false alarms. Once a memory corruption occurs, the program is in an inconsistent
+ state, which could lead to confusing results and potentially misleading
+ subsequent reports.
+
+If your process is sandboxed and you are running on OS X 10.10 or earlier, you
+will need to set ``DYLD_INSERT_LIBRARIES`` environment variable and point it to
+the ASan library that is packaged with the compiler used to build the
+executable. (You can find the library by searching for dynamic libraries with
+``asan`` in their name.) If the environment variable is not set, the process will
+try to re-exec. Also keep in mind that when moving the executable to another machine,
+the ASan library will also need to be copied over.
+
+Symbolizing the Reports
+=========================
+
+To make AddressSanitizer symbolize its output
+you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to
+the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your
+``$PATH``):
+
+.. code-block:: console
+
+ % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out
+ ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
+ READ of size 4 at 0x7f7ddab8c084 thread T0
+ #0 0x403c8c in main example_UseAfterFree.cc:4
+ #1 0x7f7ddabcac4d in __libc_start_main ??:0
+ 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
+ freed by thread T0 here:
+ #0 0x404704 in operator delete[](void*) ??:0
+ #1 0x403c53 in main example_UseAfterFree.cc:4
+ #2 0x7f7ddabcac4d in __libc_start_main ??:0
+ previously allocated by thread T0 here:
+ #0 0x404544 in operator new[](unsigned long) ??:0
+ #1 0x403c43 in main example_UseAfterFree.cc:2
+ #2 0x7f7ddabcac4d in __libc_start_main ??:0
+ ==9442== ABORTING
+
+If that does not work for you (e.g. your process is sandboxed), you can use a
+separate script to symbolize the result offline (online symbolization can be
+force disabled by setting ``ASAN_OPTIONS=symbolize=0``):
+
+.. code-block:: console
+
+ % ASAN_OPTIONS=symbolize=0 ./a.out 2> log
+ % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
+ ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
+ READ of size 4 at 0x7f7ddab8c084 thread T0
+ #0 0x403c8c in main example_UseAfterFree.cc:4
+ #1 0x7f7ddabcac4d in __libc_start_main ??:0
+ ...
+
+Note that on macOS you may need to run ``dsymutil`` on your binary to have the
+file\:line info in the AddressSanitizer reports.
+
+Additional Checks
+=================
+
+Initialization order checking
+-----------------------------
+
+AddressSanitizer can optionally detect dynamic initialization order problems,
+when initialization of globals defined in one translation unit uses
+globals defined in another translation unit. To enable this check at runtime,
+you should set environment variable
+``ASAN_OPTIONS=check_initialization_order=1``.
+
+Note that this option is not supported on macOS.
+
+Memory leak detection
+---------------------
+
+For more information on leak detector in AddressSanitizer, see
+:doc:`LeakSanitizer`. The leak detection is turned on by default on Linux,
+and can be enabled using ``ASAN_OPTIONS=detect_leaks=1`` on macOS;
+however, it is not yet supported on other platforms.
+
+Issue Suppression
+=================
+
+AddressSanitizer is not expected to produce false positives. If you see one,
+look again; most likely it is a true positive!
+
+Suppressing Reports in External Libraries
+-----------------------------------------
+Runtime interposition allows AddressSanitizer to find bugs in code that is
+not being recompiled. If you run into an issue in external libraries, we
+recommend immediately reporting it to the library maintainer so that it
+gets addressed. However, you can use the following suppression mechanism
+to unblock yourself and continue on with the testing. This suppression
+mechanism should only be used for suppressing issues in external code; it
+does not work on code recompiled with AddressSanitizer. To suppress errors
+in external libraries, set the ``ASAN_OPTIONS`` environment variable to point
+to a suppression file. You can either specify the full path to the file or the
+path of the file relative to the location of your executable.
+
+.. code-block:: bash
+
+ ASAN_OPTIONS=suppressions=MyASan.supp
+
+Use the following format to specify the names of the functions or libraries
+you want to suppress. You can see these in the error report. Remember that
+the narrower the scope of the suppression, the more bugs you will be able to
+catch.
+
+.. code-block:: bash
+
+ interceptor_via_fun:NameOfCFunctionToSuppress
+ interceptor_via_fun:-[ClassName objCMethodToSuppress:]
+ interceptor_via_lib:NameOfTheLibraryToSuppress
+
+Conditional Compilation with ``__has_feature(address_sanitizer)``
+-----------------------------------------------------------------
+
+In some cases one may need to execute different code depending on whether
+AddressSanitizer is enabled.
+:ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
+this purpose.
+
+.. code-block:: c
+
+ #if defined(__has_feature)
+ # if __has_feature(address_sanitizer)
+ // code that builds only under AddressSanitizer
+ # endif
+ #endif
+
+Disabling Instrumentation with ``__attribute__((no_sanitize("address")))``
+--------------------------------------------------------------------------
+
+Some code should not be instrumented by AddressSanitizer. One may use
+the attribute ``__attribute__((no_sanitize("address")))`` (which has
+deprecated synonyms `no_sanitize_address` and
+`no_address_safety_analysis`) to disable instrumentation of a
+particular function. This attribute may not be supported by other
+compilers, so we suggest to use it together with
+``__has_feature(address_sanitizer)``.
+
+The same attribute used on a global variable prevents AddressSanitizer
+from adding redzones around it and detecting out of bounds accesses.
+
+Suppressing Errors in Recompiled Code (Blacklist)
+-------------------------------------------------
+
+AddressSanitizer supports ``src`` and ``fun`` entity types in
+:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
+in the specified source files or functions. Additionally, AddressSanitizer
+introduces ``global`` and ``type`` entity types that can be used to
+suppress error reports for out-of-bound access to globals with certain
+names and types (you may only specify class or struct types).
+
+You may use an ``init`` category to suppress reports about initialization-order
+problems happening in certain source files or with certain global variables.
+
+.. code-block:: bash
+
+ # Suppress error reports for code in a file or in a function:
+ src:bad_file.cpp
+ # Ignore all functions with names containing MyFooBar:
+ fun:*MyFooBar*
+ # Disable out-of-bound checks for global:
+ global:bad_array
+ # Disable out-of-bound checks for global instances of a given class ...
+ type:Namespace::BadClassName
+ # ... or a given struct. Use wildcard to deal with anonymous namespace.
+ type:Namespace2::*::BadStructName
+ # Disable initialization-order checks for globals:
+ global:bad_init_global=init
+ type:*BadInitClassSubstring*=init
+ src:bad/init/files/*=init
+
+Suppressing memory leaks
+------------------------
+
+Memory leak reports produced by :doc:`LeakSanitizer` (if it is run as a part
+of AddressSanitizer) can be suppressed by a separate file passed as
+
+.. code-block:: bash
+
+ LSAN_OPTIONS=suppressions=MyLSan.supp
+
+which contains lines of the form `leak:<pattern>`. Memory leak will be
+suppressed if pattern matches any function name, source file name, or
+library name in the symbolized stack trace of the leak report. See
+`full documentation
+<https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer#suppressions>`_
+for more details.
+
+Limitations
+===========
+
+* AddressSanitizer uses more real memory than a native run. Exact overhead
+ depends on the allocations sizes. The smaller the allocations you make the
+ bigger the overhead is.
+* AddressSanitizer uses more stack memory. We have seen up to 3x increase.
+* On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
+ virtual address space. This means that tools like ``ulimit`` may not work as
+ usually expected.
+* Static linking of executables is not supported.
+
+Supported Platforms
+===================
+
+AddressSanitizer is supported on:
+
+* Linux i386/x86\_64 (tested on Ubuntu 12.04)
+* macOS 10.7 - 10.11 (i386/x86\_64)
+* iOS Simulator
+* Android ARM
+* NetBSD i386/x86\_64
+* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
+* Windows 8.1+ (i386/x86\_64)
+
+Ports to various other platforms are in progress.
+
+Current Status
+==============
+
+AddressSanitizer is fully functional on supported platforms starting from LLVM
+3.1. The test suite is integrated into CMake build and can be run with ``make
+check-asan`` command.
+
+The Windows port is functional and is used by Chrome and Firefox, but it is not
+as well supported as the other ports.
+
+More Information
+================
+
+`<https://github.com/google/sanitizers/wiki/AddressSanitizer>`_
Added: www-releases/trunk/9.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,5546 @@
+..
+ -------------------------------------------------------------------
+ NOTE: This file is automatically generated by running clang-tblgen
+ -gen-attr-docs. Do not edit this file by hand!!
+ -------------------------------------------------------------------
+
+===================
+Attributes in Clang
+===================
+.. contents::
+ :local:
+
+.. |br| raw:: html
+
+ <br/>
+
+Introduction
+============
+
+This page lists the attributes currently supported by Clang.
+
+Function Attributes
+===================
+
+
+#pragma omp declare simd
+------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","","``omp declare simd``",""
+
+The `declare simd` 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 `declare simd`
+directive is a declarative directive. There may be multiple `declare simd`
+directives for a function. The use of a `declare simd` 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 `declare simd` construct is as follows:
+
+ .. code-block:: none
+
+ #pragma omp declare simd [clause[[,] clause] ...] new-line
+ [#pragma omp declare simd [clause[[,] clause] ...] new-line]
+ [...]
+ function definition or declaration
+
+where clause is one of the following:
+
+ .. code-block:: none
+
+ simdlen(length)
+ linear(argument-list[:constant-linear-step])
+ aligned(argument-list[:alignment])
+ uniform(argument-list)
+ inbranch
+ notinbranch
+
+
+#pragma omp declare target
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","","``omp declare target``",""
+
+The `declare target` directive specifies that variables and functions are mapped
+to a device for OpenMP offload mechanism.
+
+The syntax of the declare target directive is as follows:
+
+ .. code-block:: c
+
+ #pragma omp declare target new-line
+ declarations-definition-seq
+ #pragma omp end declare target new-line
+
+
+_Noreturn
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``_Noreturn``","",""
+
+A function declared as ``_Noreturn`` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as ``_Noreturn``
+that appears to be capable of returning to its caller.
+
+
+abi_tag
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``abi_tag``","``gnu::abi_tag``","","","","","Yes"
+
+The ``abi_tag`` 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 ``abi_tag`` attribute, it is possible to have different mangled names for
+a global variable of the class type. Therefore, the old code could keep using
+the old manged name and the new code will use the new mangled name with tags.
+
+
+acquire_capability, acquire_shared_capability
+---------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``acquire_capability`` |br| ``acquire_shared_capability`` |br| ``exclusive_lock_function`` |br| ``shared_lock_function``","``clang::acquire_capability`` |br| ``clang::acquire_shared_capability``","","","","",""
+
+Marks a function as acquiring a capability.
+
+
+alloc_align
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``alloc_align``","``gnu::alloc_align``","","","","",""
+
+Use ``__attribute__((alloc_align(<alignment>))`` on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) is at least as aligned as the value of the indicated parameter. The
+parameter is given by its index in the list of formal parameters; the first
+parameter has index 1 unless the function is a C++ non-static member function,
+in which case the first parameter has index 2 to account for the implicit ``this``
+parameter.
+
+.. code-block:: c++
+
+ // The returned pointer has the alignment specified by the first parameter.
+ void *a(size_t align) __attribute__((alloc_align(1)));
+
+ // The returned pointer has the alignment specified by the second parameter.
+ void *b(void *v, size_t align) __attribute__((alloc_align(2)));
+
+ // The returned pointer has the alignment specified by the second visible
+ // parameter, however it must be adjusted for the implicit 'this' parameter.
+ void *Foo::b(void *v, size_t align) __attribute__((alloc_align(3)));
+
+Note that this attribute merely informs the compiler that a function always
+returns a sufficiently aligned pointer. It does not cause the compiler to
+emit code to enforce that alignment. The behavior is undefined if the returned
+poitner is not sufficiently aligned.
+
+
+alloc_size
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``alloc_size``","``gnu::alloc_size``","","","","","Yes"
+
+The ``alloc_size`` 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 pointer. ``alloc_size`` takes one or two arguments.
+
+- ``alloc_size(N)`` implies that argument number N equals the number of
+ available bytes at the returned pointer.
+- ``alloc_size(N, M)`` implies that the product of argument number N and
+ argument number M equals the number of available bytes at the returned
+ pointer.
+
+Argument numbers are 1-based.
+
+An example of how to use ``alloc_size``
+
+.. code-block:: c
+
+ void *my_malloc(int a) __attribute__((alloc_size(1)));
+ void *my_calloc(int a, int b) __attribute__((alloc_size(1, 2)));
+
+ int main() {
+ void *const p = my_malloc(100);
+ assert(__builtin_object_size(p, 0) == 100);
+ void *const a = my_calloc(20, 5);
+ assert(__builtin_object_size(a, 0) == 100);
+ }
+
+.. Note:: This attribute works differently in clang than it does in GCC.
+ Specifically, clang will only trace ``const`` pointers (as above); we give up
+ on pointers that are not marked as ``const``. In the vast majority of cases,
+ this is unimportant, because LLVM has support for the ``alloc_size``
+ attribute. However, this may cause mildly unintuitive behavior when used with
+ other attributes, such as ``enable_if``.
+
+
+allocator
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","``allocator``","","",""
+
+The ``__declspec(allocator)`` attribute is applied to functions that allocate
+memory, such as operator new in C++. When CodeView debug information is emitted
+(enabled by ``clang -gcodeview`` or ``clang-cl /Z7``), Clang will attempt to
+record the code offset of heap allocation call sites in the debug info. It will
+also record the type being allocated using some local heuristics. The Visual
+Studio debugger uses this information to `profile memory usage`_.
+
+.. _profile memory usage: https://docs.microsoft.com/en-us/visualstudio/profiling/memory-usage
+
+This attribute does not affect optimizations in any way, unlike GCC's
+``__attribute__((malloc))``.
+
+
+artificial
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``artificial``","``gnu::artificial``","","","","",""
+
+The ``artificial`` attribute can be applied to an inline function. If such a
+function is inlined, the attribute indicates that debuggers should associate
+the resulting instructions with the call site, rather than with the
+corresponding line within the inlined callee.
+
+
+assert_capability, assert_shared_capability
+-------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``assert_capability`` |br| ``assert_shared_capability``","``clang::assert_capability`` |br| ``clang::assert_shared_capability``","","","","",""
+
+Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.
+
+
+assume_aligned
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``assume_aligned``","``gnu::assume_aligned``","","","","","Yes"
+
+Use ``__attribute__((assume_aligned(<alignment>[,<offset>]))`` 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.
+
+.. code-block:: c++
+
+ // The returned pointer value has 32-byte alignment.
+ void *a() __attribute__((assume_aligned (32)));
+
+ // The returned pointer value is 4 bytes greater than an address having
+ // 32-byte alignment.
+ void *b() __attribute__((assume_aligned (32, 4)));
+
+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.
+
+
+availability
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``availability``","``clang::availability``","``clang::availability``","","","","Yes"
+
+The ``availability`` 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 ``f``:
+
+.. code-block:: c++
+
+ void f(void) __attribute__((availability(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
+
+The availability attribute states that ``f`` was introduced in macOS 10.4,
+deprecated in macOS 10.6, and obsoleted in macOS 10.7. This information
+is used by Clang to determine when it is safe to use ``f``: for example, if
+Clang is instructed to compile code for macOS 10.5, a call to ``f()``
+succeeds. If Clang is instructed to compile code for macOS 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 macOS 10.7, the call
+fails because ``f()`` is no longer available.
+
+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:
+
+introduced=\ *version*
+ The first version in which this declaration was introduced.
+
+deprecated=\ *version*
+ The first version in which this declaration was deprecated, meaning that
+ users should migrate away from this API.
+
+obsoleted=\ *version*
+ The first version in which this declaration was obsoleted, meaning that it
+ was removed completely and can no longer be used.
+
+unavailable
+ This declaration is never available on this platform.
+
+message=\ *string-literal*
+ 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.
+
+replacement=\ *string-literal*
+ 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.
+
+Multiple availability attributes can be placed on a declaration, which may
+correspond to different platforms. For most platforms, the availability
+attribute with the platform corresponding to the target platform will be used;
+any others will be ignored. However, the availability for ``watchOS`` and
+``tvOS`` can be implicitly inferred from an ``iOS`` availability attribute.
+Any explicit availability attributes for those platforms are still prefered over
+the implicitly inferred availability attributes. If no availability attribute
+specifies availability for the current target platform, the availability
+attributes are ignored. Supported platforms are:
+
+``ios``
+ Apple's iOS operating system. The minimum deployment target is specified by
+ the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*``
+ command-line arguments.
+
+``macos``
+ Apple's macOS operating system. The minimum deployment target is
+ specified by the ``-mmacosx-version-min=*version*`` command-line argument.
+ ``macosx`` is supported for backward-compatibility reasons, but it is
+ deprecated.
+
+``tvos``
+ Apple's tvOS operating system. The minimum deployment target is specified by
+ the ``-mtvos-version-min=*version*`` command-line argument.
+
+``watchos``
+ Apple's watchOS operating system. The minimum deployment target is specified by
+ the ``-mwatchos-version-min=*version*`` command-line argument.
+
+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 `weakly linked
+<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
+as if the ``weak_import`` 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.
+
+The flag ``strict`` 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.
+
+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:
+
+.. code-block:: c
+
+ void g(void) __attribute__((availability(macos,introduced=10.4)));
+ void g(void) __attribute__((availability(macos,introduced=10.4))); // okay, matches
+ void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
+ void g(void); // okay, inherits both macos and ios availability from above.
+ void g(void) __attribute__((availability(macos,introduced=10.5))); // error: mismatch
+
+When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
+
+.. code-block:: objc
+
+ @interface A
+ - (id)method __attribute__((availability(macos,introduced=10.4)));
+ - (id)method2 __attribute__((availability(macos,introduced=10.4)));
+ @end
+
+ @interface B : A
+ - (id)method __attribute__((availability(macos,introduced=10.3))); // okay: method moved into base class later
+ - (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4
+ @end
+
+Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from
+``<os/availability.h>`` can simplify the spelling:
+
+.. code-block:: objc
+
+ @interface A
+ - (id)method API_AVAILABLE(macos(10.11)));
+ - (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0));
+ @end
+
+Availability attributes can also be applied using a ``#pragma clang attribute``.
+Any explicit availability attribute whose platform corresponds to the target
+platform is applied to a declaration regardless of the availability attributes
+specified in the pragma. For example, in the code below,
+``hasExplicitAvailabilityAttribute`` will use the ``macOS`` availability
+attribute that is specified with the declaration, whereas
+``getsThePragmaAvailabilityAttribute`` will use the ``macOS`` availability
+attribute that is applied by the pragma.
+
+.. code-block:: c
+
+ #pragma clang attribute push (__attribute__((availability(macOS, introduced=10.12))), apply_to=function)
+ void getsThePragmaAvailabilityAttribute(void);
+ void hasExplicitAvailabilityAttribute(void) __attribute__((availability(macos,introduced=10.4)));
+ #pragma clang attribute pop
+
+For platforms like ``watchOS`` and ``tvOS``, whose availability attributes can
+be implicitly inferred from an ``iOS`` availability attribute, the logic is
+slightly more complex. The explicit and the pragma-applied availability
+attributes whose platform corresponds to the target platform are applied as
+described in the previous paragraph. However, the implicitly inferred attributes
+are applied to a declaration only when there is no explicit or pragma-applied
+availability attribute whose platform corresponds to the target platform. For
+example, the function below will receive the ``tvOS`` availability from the
+pragma rather than using the inferred ``iOS`` availability from the declaration:
+
+.. code-block:: c
+
+ #pragma clang attribute push (__attribute__((availability(tvOS, introduced=12.0))), apply_to=function)
+ void getsThePragmaTVOSAvailabilityAttribute(void) __attribute__((availability(iOS,introduced=11.0)));
+ #pragma clang attribute pop
+
+The compiler is also able to apply implicly inferred attributes from a pragma
+as well. For example, when targeting ``tvOS``, the function below will receive
+a ``tvOS`` availability attribute that is implicitly inferred from the ``iOS``
+availability attribute applied by the pragma:
+
+.. code-block:: c
+
+ #pragma clang attribute push (__attribute__((availability(iOS, introduced=12.0))), apply_to=function)
+ void infersTVOSAvailabilityFromPragma(void);
+ #pragma clang attribute pop
+
+The implicit attributes that are inferred from explicitly specified attributes
+whose platform corresponds to the target platform are applied to the declaration
+even if there is an availability attribute that can be inferred from a pragma.
+For example, the function below will receive the ``tvOS, introduced=11.0``
+availability that is inferred from the attribute on the declaration rather than
+inferring availability from the pragma:
+
+.. code-block:: c
+
+ #pragma clang attribute push (__attribute__((availability(iOS, unavailable))), apply_to=function)
+ void infersTVOSAvailabilityFromAttributeNextToDeclaration(void)
+ __attribute__((availability(iOS,introduced=11.0)));
+ #pragma clang attribute pop
+
+Also see the documentation for `@available
+<http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-available>`_
+
+
+callback
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``callback``","``clang::callback``","``clang::callback``","","","","Yes"
+
+The ``callback`` attribute specifies that the annotated function may invoke the
+specified callback zero or more times. The callback, as well as the passed
+arguments, are identified by their parameter name or position (starting with
+1!) in the annotated function. The first position in the attribute identifies
+the callback callee, the following positions declare describe its arguments.
+The callback callee is required to be callable with the number, and order, of
+the specified arguments. The index `0`, or the identifier `this`, is used to
+represent an implicit "this" pointer in class methods. If there is no implicit
+"this" pointer it shall not be referenced. The index '-1', or the name "__",
+represents an unknown callback callee argument. This can be a value which is
+not present in the declared parameter list, or one that is, but is potentially
+inspected, captured, or modified. Parameter names and indices can be mixed in
+the callback attribute.
+
+The ``callback`` attribute, which is directly translated to ``callback``
+metadata <http://llvm.org/docs/LangRef.html#callback-metadata>, make the
+connection between the call to the annotated function and the callback callee.
+This can enable interprocedural optimizations which were otherwise impossible.
+If a function parameter is mentioned in the ``callback`` attribute, through its
+position, it is undefined if that parameter is used for anything other than the
+actual callback. Inspected, captured, or modified parameters shall not be
+listed in the ``callback`` metadata.
+
+Example encodings for the callback performed by `pthread_create` are shown
+below. The explicit attribute annotation indicates that the third parameter
+(`start_routine`) is called zero or more times by the `pthread_create` function,
+and that the fourth parameter (`arg`) is passed along. Note that the callback
+behavior of `pthread_create` is automatically recognized by Clang. In addition,
+the declarations of `__kmpc_fork_teams` and `__kmpc_fork_call`, generated for
+`#pragma omp target teams` and `#pragma omp parallel`, respectively, are also
+automatically recognized as broker functions. Further functions might be added
+in the future.
+
+ .. code-block:: c
+
+ __attribute__((callback (start_routine, arg)))
+ int pthread_create(pthread_t *thread, const pthread_attr_t *attr,
+ void *(*start_routine) (void *), void *arg);
+
+ __attribute__((callback (3, 4)))
+ int pthread_create(pthread_t *thread, const pthread_attr_t *attr,
+ void *(*start_routine) (void *), void *arg);
+
+
+carries_dependency
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``carries_dependency``","``carries_dependency``","","","","","Yes"
+
+The ``carries_dependency`` attribute specifies dependency propagation into and
+out of functions.
+
+When specified on a function or Objective-C method, the ``carries_dependency``
+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.
+
+Note, this attribute does not change the meaning of the program, but may result
+in generation of more efficient code.
+
+
+cf_consumed
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``cf_consumed``","``clang::cf_consumed``","``clang::cf_consumed``","","","","Yes"
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+cf_returns_not_retained
+-----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``cf_returns_not_retained``","``clang::cf_returns_not_retained``","``clang::cf_returns_not_retained``","","","",""
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+cf_returns_retained
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``cf_returns_retained``","``clang::cf_returns_retained``","``clang::cf_returns_retained``","","","",""
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+code_seg
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","``code_seg``","","",""
+
+The ``__declspec(code_seg)`` attribute enables the placement of code into separate
+named segments that can be paged or locked in memory individually. This attribute
+is used to control the placement of instantiated templates and compiler-generated
+code. See the documentation for `__declspec(code_seg)`_ on MSDN.
+
+.. _`__declspec(code_seg)`: http://msdn.microsoft.com/en-us/library/dn636922.aspx
+
+
+convergent
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``convergent``","``clang::convergent``","``clang::convergent``","","","","Yes"
+
+The ``convergent`` attribute can be placed on a function declaration. It is
+translated into the LLVM ``convergent`` attribute, which indicates that the call
+instructions of a function with this attribute cannot be made control-dependent
+on any additional values.
+
+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.
+
+This attribute is different from ``noduplicate`` 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.
+
+Sample usage:
+.. code-block:: c
+
+ void convfunc(void) __attribute__((convergent));
+ // Setting it as a C++11 attribute is also valid in a C++ program.
+ // void convfunc(void) [[clang::convergent]];
+
+
+cpu_dispatch
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``cpu_dispatch``","``clang::cpu_dispatch``","``clang::cpu_dispatch``","``cpu_dispatch``","","","Yes"
+
+The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and
+resolve multiversioned functions. This form of multiversioning provides a
+mechanism for declaring versions across translation units and manually
+specifying the resolved function list. A specified CPU defines a set of minimum
+features that are required for the function to be called. The result of this is
+that future processors execute the most restrictive version of the function the
+new processor can execute.
+
+Function versions are defined with ``cpu_specific``, which takes one or more CPU
+names as a parameter. For example:
+
+.. code-block:: c
+
+ // Declares and defines the ivybridge version of single_cpu.
+ __attribute__((cpu_specific(ivybridge)))
+ void single_cpu(void){}
+
+ // Declares and defines the atom version of single_cpu.
+ __attribute__((cpu_specific(atom)))
+ void single_cpu(void){}
+
+ // Declares and defines both the ivybridge and atom version of multi_cpu.
+ __attribute__((cpu_specific(ivybridge, atom)))
+ void multi_cpu(void){}
+
+A dispatching (or resolving) function can be declared anywhere in a project's
+source code with ``cpu_dispatch``. This attribute takes one or more CPU names
+as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch``
+are not expected to be defined, only declared. If such a marked function has a
+definition, any side effects of the function are ignored; trivial function
+bodies are permissible for ICC compatibility.
+
+.. code-block:: c
+
+ // Creates a resolver for single_cpu above.
+ __attribute__((cpu_dispatch(ivybridge, atom)))
+ void single_cpu(void){}
+
+ // Creates a resolver for multi_cpu, but adds a 3rd version defined in another
+ // translation unit.
+ __attribute__((cpu_dispatch(ivybridge, atom, sandybridge)))
+ void multi_cpu(void){}
+
+Note that it is possible to have a resolving function that dispatches based on
+more or fewer options than are present in the program. Specifying fewer will
+result in the omitted options not being considered during resolution. Specifying
+a version for resolution that isn't defined in the program will result in a
+linking failure.
+
+It is also possible to specify a CPU name of ``generic`` which will be resolved
+if the executing processor doesn't satisfy the features required in the CPU
+name. The behavior of a program executing on a processor that doesn't satisfy
+any option of a multiversioned function is undefined.
+
+
+cpu_specific
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``cpu_specific``","``clang::cpu_specific``","``clang::cpu_specific``","``cpu_specific``","","","Yes"
+
+The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and
+resolve multiversioned functions. This form of multiversioning provides a
+mechanism for declaring versions across translation units and manually
+specifying the resolved function list. A specified CPU defines a set of minimum
+features that are required for the function to be called. The result of this is
+that future processors execute the most restrictive version of the function the
+new processor can execute.
+
+Function versions are defined with ``cpu_specific``, which takes one or more CPU
+names as a parameter. For example:
+
+.. code-block:: c
+
+ // Declares and defines the ivybridge version of single_cpu.
+ __attribute__((cpu_specific(ivybridge)))
+ void single_cpu(void){}
+
+ // Declares and defines the atom version of single_cpu.
+ __attribute__((cpu_specific(atom)))
+ void single_cpu(void){}
+
+ // Declares and defines both the ivybridge and atom version of multi_cpu.
+ __attribute__((cpu_specific(ivybridge, atom)))
+ void multi_cpu(void){}
+
+A dispatching (or resolving) function can be declared anywhere in a project's
+source code with ``cpu_dispatch``. This attribute takes one or more CPU names
+as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch``
+are not expected to be defined, only declared. If such a marked function has a
+definition, any side effects of the function are ignored; trivial function
+bodies are permissible for ICC compatibility.
+
+.. code-block:: c
+
+ // Creates a resolver for single_cpu above.
+ __attribute__((cpu_dispatch(ivybridge, atom)))
+ void single_cpu(void){}
+
+ // Creates a resolver for multi_cpu, but adds a 3rd version defined in another
+ // translation unit.
+ __attribute__((cpu_dispatch(ivybridge, atom, sandybridge)))
+ void multi_cpu(void){}
+
+Note that it is possible to have a resolving function that dispatches based on
+more or fewer options than are present in the program. Specifying fewer will
+result in the omitted options not being considered during resolution. Specifying
+a version for resolution that isn't defined in the program will result in a
+linking failure.
+
+It is also possible to specify a CPU name of ``generic`` which will be resolved
+if the executing processor doesn't satisfy the features required in the CPU
+name. The behavior of a program executing on a processor that doesn't satisfy
+any option of a multiversioned function is undefined.
+
+
+diagnose_if
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``diagnose_if``","","","","","",""
+
+The ``diagnose_if`` 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:
+
+.. code-block:: c
+
+ int abs(int a)
+ __attribute__((diagnose_if(a >= 0, "Redundant abs call", "warning")));
+ int must_abs(int a)
+ __attribute__((diagnose_if(a >= 0, "Redundant abs call", "error")));
+
+ int val = abs(1); // warning: Redundant abs call
+ int val2 = must_abs(1); // error: Redundant abs call
+ int val3 = abs(val);
+ int val4 = must_abs(val); // Because run-time checks are not emitted for
+ // diagnose_if attributes, this executes without
+ // issue.
+
+
+``diagnose_if`` is closely related to ``enable_if``, with a few key differences:
+
+* Overload resolution is not aware of ``diagnose_if`` attributes: they're
+ considered only after we select the best candidate from a given candidate set.
+* Function declarations that differ only in their ``diagnose_if`` attributes are
+ considered to be redeclarations of the same function (not overloads).
+* If the condition provided to ``diagnose_if`` cannot be evaluated, no
+ diagnostic will be emitted.
+
+Otherwise, ``diagnose_if`` is essentially the logical negation of ``enable_if``.
+
+As a result of bullet number two, ``diagnose_if`` attributes will stack on the
+same function. For example:
+
+.. code-block:: c
+
+ int foo() __attribute__((diagnose_if(1, "diag1", "warning")));
+ int foo() __attribute__((diagnose_if(1, "diag2", "warning")));
+
+ int bar = foo(); // warning: diag1
+ // warning: diag2
+ int (*fooptr)(void) = foo; // warning: diag1
+ // warning: diag2
+
+ constexpr int supportsAPILevel(int N) { return N < 5; }
+ int baz(int a)
+ __attribute__((diagnose_if(!supportsAPILevel(10),
+ "Upgrade to API level 10 to use baz", "error")));
+ int baz(int a)
+ __attribute__((diagnose_if(!a, "0 is not recommended.", "warning")));
+
+ int (*bazptr)(int) = baz; // error: Upgrade to API level 10 to use baz
+ int v = baz(0); // error: Upgrade to API level 10 to use baz
+
+Query for this feature with ``__has_attribute(diagnose_if)``.
+
+
+disable_tail_calls
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``disable_tail_calls``","``clang::disable_tail_calls``","``clang::disable_tail_calls``","","","","Yes"
+
+The ``disable_tail_calls`` attribute instructs the backend to not perform tail call optimization inside the marked function.
+
+For example:
+
+ .. code-block:: c
+
+ int callee(int);
+
+ int foo(int a) __attribute__((disable_tail_calls)) {
+ return callee(a); // This call is not tail-call optimized.
+ }
+
+Marking virtual functions as ``disable_tail_calls`` is legal.
+
+ .. code-block:: c++
+
+ int callee(int);
+
+ class Base {
+ public:
+ [[clang::disable_tail_calls]] virtual int foo1() {
+ return callee(); // This call is not tail-call optimized.
+ }
+ };
+
+ class Derived1 : public Base {
+ public:
+ int foo1() override {
+ return callee(); // This call is tail-call optimized.
+ }
+ };
+
+
+enable_if
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``enable_if``","","","","","","Yes"
+
+.. Note:: 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.
+
+The ``enable_if`` 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 ``overloadable`` attribute, this feature is also
+available in C.
+
+.. code-block:: c++
+
+ int isdigit(int c);
+ int isdigit(int c) __attribute__((enable_if(c <= -1 || c > 255, "chosen when 'c' is out of range"))) __attribute__((unavailable("'c' must have the value of an unsigned char or EOF")));
+
+ void foo(char c) {
+ isdigit(c);
+ isdigit(10);
+ isdigit(-10); // results in a compile-time error.
+ }
+
+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.
+
+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.
+
+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:
+
+.. code-block:: c++
+
+ __attribute__((always_inline))
+ static inline size_t strnlen(const char *s, size_t maxlen)
+ __attribute__((overloadable))
+ __attribute__((enable_if(__builtin_object_size(s, 0) != -1))),
+ "chosen when the buffer size is known but 'maxlen' is not")))
+ {
+ return strnlen_chk(s, maxlen, __builtin_object_size(s, 0));
+ }
+
+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.
+
+.. code-block:: c++
+
+ void f() __attribute__((enable_if(true, ""))); // #1
+ void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2
+
+ void g(int i, int j) __attribute__((enable_if(i, ""))); // #1
+ void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2
+
+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.
+
+Query for this feature with ``__has_attribute(enable_if)``.
+
+Note that functions with one or more ``enable_if`` attributes may not have
+their address taken, unless all of the conditions specified by said
+``enable_if`` are constants that evaluate to ``true``. For example:
+
+.. code-block:: c
+
+ const int TrueConstant = 1;
+ const int FalseConstant = 0;
+ int f(int a) __attribute__((enable_if(a > 0, "")));
+ int g(int a) __attribute__((enable_if(a == 0 || a != 0, "")));
+ int h(int a) __attribute__((enable_if(1, "")));
+ int i(int a) __attribute__((enable_if(TrueConstant, "")));
+ int j(int a) __attribute__((enable_if(FalseConstant, "")));
+
+ void fn() {
+ int (*ptr)(int);
+ ptr = &f; // error: 'a > 0' is not always true
+ ptr = &g; // error: 'a == 0 || a != 0' is not a truthy constant
+ ptr = &h; // OK: 1 is a truthy constant
+ ptr = &i; // OK: 'TrueConstant' is a truthy constant
+ ptr = &j; // error: 'FalseConstant' is a constant, but not truthy
+ }
+
+Because ``enable_if`` evaluation happens during overload resolution,
+``enable_if`` 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 ``foo`` in ``bar``, but not in ``baz``:
+
+.. code-block:: c++
+
+ double foo(int i) __attribute__((enable_if(i > 0, "")));
+ void *foo(int i) __attribute__((enable_if(i <= 0, "")));
+ template <int I>
+ auto bar() { return foo(I); }
+
+ template <typename T>
+ auto baz() { return foo(T::number); }
+
+ struct WithNumber { constexpr static int number = 1; };
+ void callThem() {
+ bar<sizeof(WithNumber)>();
+ baz<WithNumber>();
+ }
+
+This is because, in ``bar``, ``foo`` is resolved prior to template
+instantiation, so the value for ``I`` isn't known (thus, both ``enable_if``
+conditions for ``foo`` fail). However, in ``baz``, ``foo`` is resolved during
+template instantiation, so the value for ``T::number`` is known.
+
+
+exclude_from_explicit_instantiation
+-----------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``exclude_from_explicit_instantiation``","``clang::exclude_from_explicit_instantiation``","``clang::exclude_from_explicit_instantiation``","","","","Yes"
+
+The ``exclude_from_explicit_instantiation`` attribute opts-out a member of a
+class template from being part of explicit template instantiations of that
+class template. This means that an explicit instantiation will not instantiate
+members of the class template marked with the attribute, but also that code
+where an extern template declaration of the enclosing class template is visible
+will not take for granted that an external instantiation of the class template
+would provide those members (which would otherwise be a link error, since the
+explicit instantiation won't provide those members). For example, let's say we
+don't want the ``data()`` method to be part of libc++'s ABI. To make sure it
+is not exported from the dylib, we give it hidden visibility:
+
+ .. code-block:: c++
+
+ // in <string>
+ template <class CharT>
+ class basic_string {
+ public:
+ __attribute__((__visibility__("hidden")))
+ const value_type* data() const noexcept { ... }
+ };
+
+ template class basic_string<char>;
+
+Since an explicit template instantiation declaration for ``basic_string<char>``
+is provided, the compiler is free to assume that ``basic_string<char>::data()``
+will be provided by another translation unit, and it is free to produce an
+external call to this function. However, since ``data()`` has hidden visibility
+and the explicit template instantiation is provided in a shared library (as
+opposed to simply another translation unit), ``basic_string<char>::data()``
+won't be found and a link error will ensue. This happens because the compiler
+assumes that ``basic_string<char>::data()`` is part of the explicit template
+instantiation declaration, when it really isn't. To tell the compiler that
+``data()`` is not part of the explicit template instantiation declaration, the
+``exclude_from_explicit_instantiation`` attribute can be used:
+
+ .. code-block:: c++
+
+ // in <string>
+ template <class CharT>
+ class basic_string {
+ public:
+ __attribute__((__visibility__("hidden")))
+ __attribute__((exclude_from_explicit_instantiation))
+ const value_type* data() const noexcept { ... }
+ };
+
+ template class basic_string<char>;
+
+Now, the compiler won't assume that ``basic_string<char>::data()`` is provided
+externally despite there being an explicit template instantiation declaration:
+the compiler will implicitly instantiate ``basic_string<char>::data()`` in the
+TUs where it is used.
+
+This attribute can be used on static and non-static member functions of class
+templates, static data members of class templates and member classes of class
+templates.
+
+
+flatten
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``flatten``","``gnu::flatten``","","","","","Yes"
+
+The ``flatten`` 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 ``noinline`` attribute.
+
+
+force_align_arg_pointer
+-----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``force_align_arg_pointer``","``gnu::force_align_arg_pointer``","","","","",""
+
+Use this attribute to force stack alignment.
+
+Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions
+(like 'movaps') that work with the stack require operands to be 16-byte aligned.
+This attribute realigns the stack in the function prologue to make sure the
+stack can be used with SSE instructions.
+
+Note that the x86_64 ABI forces 16-byte stack alignment at the call site.
+Because of this, 'force_align_arg_pointer' is not needed on x86_64, except in
+rare cases where the caller does not align the stack properly (e.g. flow
+jumps from i386 arch code).
+
+ .. code-block:: c
+
+ __attribute__ ((force_align_arg_pointer))
+ void f () {
+ ...
+ }
+
+
+format
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``format``","``gnu::format``","","","","",""
+
+Clang supports the ``format`` attribute, which indicates that the function
+accepts a ``printf`` or ``scanf``-like format string and corresponding
+arguments or a ``va_list`` that contains these arguments.
+
+Please see `GCC documentation about format attribute
+<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
+about attribute syntax.
+
+Clang implements two kinds of checks with this attribute.
+
+#. Clang checks that the function with the ``format`` attribute is called with
+ a format string that uses format specifiers that are allowed, and that
+ arguments match the format string. This is the ``-Wformat`` warning, it is
+ on by default.
+
+#. Clang checks that the format string argument is a literal string. This is
+ the ``-Wformat-nonliteral`` warning, it is off by default.
+
+ Clang implements this mostly the same way as GCC, but there is a difference
+ for functions that accept a ``va_list`` argument (for example, ``vprintf``).
+ GCC does not emit ``-Wformat-nonliteral`` 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:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__scanf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning: format string is not a string literal
+ }
+
+ In this case we warn because ``s`` contains a format string for a
+ ``scanf``-like function, but it is passed to a ``printf``-like function.
+
+ If the attribute is removed, clang still warns, because the format string is
+ not a string literal.
+
+ Another example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__printf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning
+ }
+
+ In this case Clang does not warn because the format string ``s`` and
+ the corresponding arguments are annotated. If the arguments are
+ incorrect, the caller of ``foo`` will receive a warning.
+
+
+gnu_inline
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``gnu_inline``","``gnu::gnu_inline``","","","","","Yes"
+
+The ``gnu_inline`` changes the meaning of ``extern inline`` to use GNU inline
+semantics, meaning:
+
+* If any declaration that is declared ``inline`` is not declared ``extern``,
+ then the ``inline`` keyword is just a hint. In particular, an out-of-line
+ definition is still emitted for a function with external linkage, even if all
+ call sites are inlined, unlike in C99 and C++ inline semantics.
+
+* If all declarations that are declared ``inline`` are also declared
+ ``extern``, then the function body is present only for inlining and no
+ out-of-line version is emitted.
+
+Some important consequences: ``static inline`` emits an out-of-line
+version if needed, a plain ``inline`` definition emits an out-of-line version
+always, and an ``extern inline`` definition (in a header) followed by a
+(non-``extern``) ``inline`` declaration in a source file emits an out-of-line
+version of the function in that source file but provides the function body for
+inlining to all includers of the header.
+
+Either ``__GNUC_GNU_INLINE__`` (GNU inline semantics) or
+``__GNUC_STDC_INLINE__`` (C99 semantics) will be defined (they are mutually
+exclusive). If ``__GNUC_STDC_INLINE__`` is defined, then the ``gnu_inline``
+function attribute can be used to get GNU inline semantics on a per function
+basis. If ``__GNUC_GNU_INLINE__`` is defined, then the translation unit is
+already being compiled with GNU inline semantics as the implied default. It is
+unspecified which macro is defined in a C++ compilation.
+
+GNU inline semantics are the default behavior with ``-std=gnu89``,
+``-std=c89``, ``-std=c94``, or ``-fgnu89-inline``.
+
+
+ifunc
+-----
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``ifunc``","``gnu::ifunc``","","","","","Yes"
+
+``__attribute__((ifunc("resolver")))`` is used to mark that the address of a declaration should be resolved at runtime by calling a resolver function.
+
+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 ``static``. The resolver function should return a pointer.
+
+The ``ifunc`` attribute may only be used on a function declaration. A function declaration with an ``ifunc`` 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.
+
+Not all targets support this attribute. ELF target support depends on both the linker and runtime linker, and is available in at least lld 4.0 and later, binutils 2.20.1 and later, glibc v2.11.1 and later, and FreeBSD 9.1 and later. Non-ELF targets currently do not support this attribute.
+
+
+import_module
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``import_module``","``clang::import_module``","``clang::import_module``","","","","Yes"
+
+Clang supports the ``__attribute__((import_module(<module_name>)))``
+attribute for the WebAssembly target. This attribute may be attached to a
+function declaration, where it modifies how the symbol is to be imported
+within the WebAssembly linking environment.
+
+WebAssembly imports use a two-level namespace scheme, consisting of a module
+name, which typically identifies a module from which to import, and a field
+name, which typically identifies a field from that module to import. By
+default, module names for C/C++ symbols are assigned automatically by the
+linker. This attribute can be used to override the default behavior, and
+reuqest a specific module name be used instead.
+
+
+import_name
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``import_name``","``clang::import_name``","``clang::import_name``","","","","Yes"
+
+Clang supports the ``__attribute__((import_name(<name>)))``
+attribute for the WebAssembly target. This attribute may be attached to a
+function declaration, where it modifies how the symbol is to be imported
+within the WebAssembly linking environment.
+
+WebAssembly imports use a two-level namespace scheme, consisting of a module
+name, which typically identifies a module from which to import, and a field
+name, which typically identifies a field from that module to import. By
+default, field names for C/C++ symbols are the same as their C/C++ symbol
+names. This attribute can be used to override the default behavior, and
+reuqest a specific field name be used instead.
+
+
+internal_linkage
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``internal_linkage``","``clang::internal_linkage``","``clang::internal_linkage``","","","","Yes"
+
+The ``internal_linkage`` attribute changes the linkage type of the declaration to internal.
+This is similar to C-style ``static``, 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.
+
+
+interrupt (ARM)
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``interrupt``","``gnu::interrupt``","","","","",""
+
+Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` 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.
+
+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".
+
+The semantics are as follows:
+
+- 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.
+- 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.
+- 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.
+
+ Specifically, interrupt kinds other than "FIQ" will save all core registers
+ except "lr" and "sp". "FIQ" interrupts will save r0-r7.
+- 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.
+
+ 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.
+
+
+interrupt (AVR)
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``interrupt``","``gnu::interrupt``","","","","","Yes"
+
+Clang supports the GNU style ``__attribute__((interrupt))`` attribute on
+AVR 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.
+
+On the AVR, the hardware globally disables interrupts when an interrupt is executed.
+The first instruction of an interrupt handler declared with this attribute is a SEI
+instruction to re-enable interrupts. See also the signal attribute that
+does not insert a SEI instruction.
+
+
+interrupt (MIPS)
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``interrupt``","``gnu::interrupt``","","","","","Yes"
+
+Clang supports the GNU style ``__attribute__((interrupt("ARGUMENT")))`` 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.
+
+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.
+
+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.
+
+The semantics are as follows:
+
+- 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.
+
+- The prologue and epilogue are modified to save and restore all non-kernel
+ registers as necessary.
+
+- The FPU is disabled in the prologue, as the floating pointer registers are not
+ spilled to the stack.
+
+- The function return sequence is changed to use an exception return instruction.
+
+- 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".
+
+
+interrupt (RISCV)
+-----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``interrupt``","``gnu::interrupt``","","","","","Yes"
+
+Clang supports the GNU style ``__attribute__((interrupt))`` attribute on RISCV
+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.
+
+Permissible values for this parameter are ``user``, ``supervisor``,
+and ``machine``. If there is no parameter, then it defaults to machine.
+
+Repeated interrupt attribute on the same declaration will cause a warning
+to be emitted. In case of repeated declarations, the last one prevails.
+
+Refer to:
+https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Function-Attributes.html
+https://riscv.org/specifications/privileged-isa/
+The RISC-V Instruction Set Manual Volume II: Privileged Architecture
+Version 1.10.
+
+
+kernel
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``kernel``","","","","","","Yes"
+
+``__attribute__((kernel))`` is used to mark a ``kernel`` function in
+RenderScript.
+
+In RenderScript, ``kernel`` functions are used to express data-parallel
+computations. The RenderScript runtime efficiently parallelizes ``kernel``
+functions to run on computational resources such as multi-core CPUs and GPUs.
+See the RenderScript_ documentation for more information.
+
+.. _RenderScript: https://developer.android.com/guide/topics/renderscript/compute.html
+
+
+lifetimebound
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``lifetimebound``","``clang::lifetimebound``","","","","",""
+
+The ``lifetimebound`` attribute indicates that a resource owned by
+a function parameter or implicit object parameter
+is retained by the return value of the annotated function
+(or, for a parameter of a constructor, in the value of the constructed object).
+It is only supported in C++.
+
+This attribute provides an experimental implementation of the facility
+described in the C++ committee paper [http://wg21.link/p0936r0](P0936R0),
+and is subject to change as the design of the corresponding functionality
+changes.
+
+
+long_call, far
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``long_call`` |br| ``far``","``gnu::long_call`` |br| ``gnu::far``","","","","","Yes"
+
+Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
+and ``__attribute__((near))`` attributes on MIPS targets. These attributes may
+only be added to function declarations and change the code generated
+by the compiler when directly calling the function. The ``near`` attribute
+allows calls to the function to be made using the ``jal`` instruction, which
+requires the function to be located in the same naturally aligned 256MB
+segment as the caller. The ``long_call`` and ``far`` attributes are synonyms
+and require the use of a different call sequence that works regardless
+of the distance between the functions.
+
+These attributes have no effect for position-independent code.
+
+These attributes take priority over command line switches such
+as ``-mlong-calls`` and ``-mno-long-calls``.
+
+
+micromips
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``micromips``","``gnu::micromips``","","","","","Yes"
+
+Clang supports the GNU style ``__attribute__((micromips))`` and
+``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
+may be attached to a function definition and instructs the backend to generate
+or not to generate microMIPS code for that function.
+
+These attributes override the `-mmicromips` and `-mno-micromips` options
+on the command line.
+
+
+mig_server_routine
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``mig_server_routine``","``clang::mig_server_routine``","``clang::mig_server_routine``","","","","Yes"
+
+The Mach Interface Generator release-on-success convention dictates
+functions that follow it to only release arguments passed to them when they
+return "success" (a ``kern_return_t`` error code that indicates that
+no errors have occured). Otherwise the release is performed by the MIG client
+that called the function. The annotation ``__attribute__((mig_server_routine))``
+is applied in order to specify which functions are expected to follow the
+convention. This allows the Static Analyzer to find bugs caused by violations of
+that convention. The attribute would normally appear on the forward declaration
+of the actual server routine in the MIG server header, but it may also be
+added to arbitrary functions that need to follow the same convention - for
+example, a user can add them to auxiliary functions called by the server routine
+that have their return value of type ``kern_return_t`` unconditionally returned
+from the routine. The attribute can be applied to C++ methods, and in this case
+it will be automatically applied to overrides if the method is virtual. The
+attribute can also be written using C++11 syntax: ``[[mig::server_routine]]``.
+
+
+min_vector_width
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``min_vector_width``","``clang::min_vector_width``","``clang::min_vector_width``","","","","Yes"
+
+Clang supports the ``__attribute__((min_vector_width(width)))`` attribute. This
+attribute may be attached to a function and informs the backend that this
+function desires vectors of at least this width to be generated. Target-specific
+maximum vector widths still apply. This means even if you ask for something
+larger than the target supports, you will only get what the target supports.
+This attribute is meant to be a hint to control target heuristics that may
+generate narrower vectors than what the target hardware supports.
+
+This is currently used by the X86 target to allow some CPUs that support 512-bit
+vectors to be limited to using 256-bit vectors to avoid frequency penalties.
+This is currently enabled with the ``-prefer-vector-width=256`` command line
+option. The ``min_vector_width`` attribute can be used to prevent the backend
+from trying to split vector operations to match the ``prefer-vector-width``. All
+X86 vector intrinsics from x86intrin.h already set this attribute. Additionally,
+use of any of the X86-specific vector builtins will implicitly set this
+attribute on the calling function. The intent is that explicitly writing vector
+code using the X86 intrinsics will prevent ``prefer-vector-width`` from
+affecting the code.
+
+
+no_caller_saved_registers
+-------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``no_caller_saved_registers``","``gnu::no_caller_saved_registers``","","","","",""
+
+Use this attribute to indicate that the specified function has no
+caller-saved registers. That is, all registers are callee-saved except for
+registers used for passing parameters to the function or returning parameters
+from the function.
+The compiler saves and restores any modified registers that were not used for
+passing or returning arguments to the function.
+
+The user can call functions specified with the 'no_caller_saved_registers'
+attribute from an interrupt handler without saving and restoring all
+call-clobbered registers.
+
+Note that 'no_caller_saved_registers' attribute is not a calling convention.
+In fact, it only overrides the decision of which registers should be saved by
+the caller, but not how the parameters are passed from the caller to the callee.
+
+For example:
+
+ .. code-block:: c
+
+ __attribute__ ((no_caller_saved_registers, fastcall))
+ void f (int arg1, int arg2) {
+ ...
+ }
+
+ In this case parameters 'arg1' and 'arg2' will be passed in registers.
+ In this case, on 32-bit x86 targets, the function 'f' will use ECX and EDX as
+ register parameters. However, it will not assume any scratch registers and
+ should save and restore any modified registers except for ECX and EDX.
+
+
+no_sanitize
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``no_sanitize``","``clang::no_sanitize``","``clang::no_sanitize``","","","","Yes"
+
+Use the ``no_sanitize`` attribute on a function or a global variable
+declaration to specify that a particular instrumentation or set of
+instrumentations should not be applied. The attribute takes a list of
+string literals, which have the same meaning as values accepted by the
+``-fno-sanitize=`` flag. For example,
+``__attribute__((no_sanitize("address", "thread")))`` specifies that
+AddressSanitizer and ThreadSanitizer should not be applied to the
+function or variable.
+
+See :ref:`Controlling Code Generation <controlling-code-generation>` for a
+full list of supported sanitizer flags.
+
+
+no_sanitize_address, no_address_safety_analysis
+-----------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``no_address_safety_analysis`` |br| ``no_sanitize_address`` |br| ``no_sanitize_thread`` |br| ``no_sanitize_memory``","``gnu::no_address_safety_analysis`` |br| ``gnu::no_sanitize_address`` |br| ``gnu::no_sanitize_thread`` |br| ``clang::no_sanitize_memory``","``clang::no_sanitize_memory``","","","","Yes"
+
+.. _langext-address_sanitizer:
+
+Use ``__attribute__((no_sanitize_address))`` on a function or a global
+variable declaration to specify that address safety instrumentation
+(e.g. AddressSanitizer) should not be applied.
+
+
+no_sanitize_memory
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``no_address_safety_analysis`` |br| ``no_sanitize_address`` |br| ``no_sanitize_thread`` |br| ``no_sanitize_memory``","``gnu::no_address_safety_analysis`` |br| ``gnu::no_sanitize_address`` |br| ``gnu::no_sanitize_thread`` |br| ``clang::no_sanitize_memory``","``clang::no_sanitize_memory``","","","","Yes"
+
+.. _langext-memory_sanitizer:
+
+Use ``__attribute__((no_sanitize_memory))`` 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.
+
+
+no_sanitize_thread
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``no_address_safety_analysis`` |br| ``no_sanitize_address`` |br| ``no_sanitize_thread`` |br| ``no_sanitize_memory``","``gnu::no_address_safety_analysis`` |br| ``gnu::no_sanitize_address`` |br| ``gnu::no_sanitize_thread`` |br| ``clang::no_sanitize_memory``","``clang::no_sanitize_memory``","","","","Yes"
+
+.. _langext-thread_sanitizer:
+
+Use ``__attribute__((no_sanitize_thread))`` 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.
+
+
+no_speculative_load_hardening
+-----------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``no_speculative_load_hardening``","``clang::no_speculative_load_hardening``","``clang::no_speculative_load_hardening``","","","","Yes"
+
+This attribute can be applied to a function declaration in order to indicate
+ that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_
+ is *not* needed for the function body. This can also be applied to a method
+ in Objective C. This attribute will take precedence over the command line flag in
+ the case where `-mspeculative-load-hardening <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening>`_ is specified.
+
+ Warning: This attribute may not prevent Speculative Load Hardening from being
+ enabled for a function which inlines a function that has the
+ 'speculative_load_hardening' attribute. This is intended to provide a
+ maximally conservative model where the code that is marked with the
+ 'speculative_load_hardening' attribute will always (even when inlined)
+ be hardened. A user of this attribute may want to mark functions called by
+ a function they do not want to be hardened with the 'noinline' attribute.
+
+ For example:
+
+ .. code-block:: c
+
+ __attribute__((speculative_load_hardening))
+ int foo(int i) {
+ return i;
+ }
+
+ // Note: bar() may still have speculative load hardening enabled if
+ // foo() is inlined into bar(). Mark foo() with __attribute__((noinline))
+ // to avoid this situation.
+ __attribute__((no_speculative_load_hardening))
+ int bar(int i) {
+ return foo(i);
+ }
+
+
+no_split_stack
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``no_split_stack``","``gnu::no_split_stack``","","","","","Yes"
+
+The ``no_split_stack`` attribute disables the emission of the split stack
+preamble for a particular function. It has no effect if ``-fsplit-stack``
+is not specified.
+
+
+no_stack_protector
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``no_stack_protector``","``clang::no_stack_protector``","``clang::no_stack_protector``","","","","Yes"
+
+Clang supports the ``__attribute__((no_stack_protector))`` attribute which disables
+the stack protector on the specified function. This attribute is useful for
+selectively disabling the stack protector on some functions when building with
+``-fstack-protector`` compiler option.
+
+For example, it disables the stack protector for the function ``foo`` but function
+``bar`` will still be built with the stack protector with the ``-fstack-protector``
+option.
+
+.. code-block:: c
+
+ int __attribute__((no_stack_protector))
+ foo (int x); // stack protection will be disabled for foo.
+
+ int bar(int y); // bar can be built with the stack protector.
+
+
+noalias
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","``noalias``","","",""
+
+The ``noalias`` 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.
+
+
+nocf_check
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``nocf_check``","``gnu::nocf_check``","","","","","Yes"
+
+Jump Oriented Programming attacks rely on tampering with addresses used by
+indirect call / jmp, e.g. redirect control-flow to non-programmer
+intended bytes in the binary.
+X86 Supports Indirect Branch Tracking (IBT) as part of Control-Flow
+Enforcement Technology (CET). IBT instruments ENDBR instructions used to
+specify valid targets of indirect call / jmp.
+The ``nocf_check`` attribute has two roles:
+1. Appertains to a function - do not add ENDBR instruction at the beginning of
+the function.
+2. Appertains to a function pointer - do not track the target function of this
+pointer (by adding nocf_check prefix to the indirect-call instruction).
+
+
+nodiscard, warn_unused_result
+-----------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``warn_unused_result``","``nodiscard`` |br| ``clang::warn_unused_result`` |br| ``gnu::warn_unused_result``","``nodiscard``","","","","Yes"
+
+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 ``[[nodiscard]]``
+(or ``__attribute__((warn_unused_result))``) and the function call appears as a
+potentially-evaluated discarded-value expression that is not explicitly cast to
+`void`.
+
+.. code-block: c++
+ struct [[nodiscard]] error_info { /*...*/ };
+ error_info enable_missile_safety_mode();
+
+ void launch_missiles();
+ void test_missiles() {
+ enable_missile_safety_mode(); // diagnoses
+ launch_missiles();
+ }
+ error_info &foo();
+ void f() { foo(); } // Does not diagnose, error_info is a reference.
+
+
+noduplicate
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``noduplicate``","``clang::noduplicate``","``clang::noduplicate``","","","","Yes"
+
+The ``noduplicate`` 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:
+
+.. code-block:: c
+
+ void nodupfunc() __attribute__((noduplicate));
+ // Setting it as a C++11 attribute is also valid
+ // void nodupfunc() [[clang::noduplicate]];
+ void foo();
+ void bar();
+
+ nodupfunc();
+ if (a > n) {
+ foo();
+ } else {
+ bar();
+ }
+
+gets possibly modified by some optimizations into code similar to this:
+
+.. code-block:: c
+
+ if (a > n) {
+ nodupfunc();
+ foo();
+ } else {
+ nodupfunc();
+ bar();
+ }
+
+where the call to "nodupfunc" is duplicated and sunk into the two branches
+of the condition.
+
+
+nomicromips
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``nomicromips``","``gnu::nomicromips``","","","","","Yes"
+
+Clang supports the GNU style ``__attribute__((micromips))`` and
+``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
+may be attached to a function definition and instructs the backend to generate
+or not to generate microMIPS code for that function.
+
+These attributes override the `-mmicromips` and `-mno-micromips` options
+on the command line.
+
+
+noreturn
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","``noreturn``","","","","","Yes"
+
+A function declared as ``[[noreturn]]`` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as ``[[noreturn]]``
+that appears to be capable of returning to its caller.
+
+
+not_tail_called
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``not_tail_called``","``clang::not_tail_called``","``clang::not_tail_called``","","","","Yes"
+
+The ``not_tail_called`` 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 ``always_inline`` cannot be marked as ``not_tail_called``.
+
+For example, it prevents tail-call optimization in the following case:
+
+ .. code-block:: c
+
+ int __attribute__((not_tail_called)) foo1(int);
+
+ int foo2(int a) {
+ return foo1(a); // No tail-call optimization on direct calls.
+ }
+
+However, it doesn't prevent tail-call optimization in this case:
+
+ .. code-block:: c
+
+ int __attribute__((not_tail_called)) foo1(int);
+
+ int foo2(int a) {
+ int (*fn)(int) = &foo1;
+
+ // not_tail_called has no effect on an indirect call even if the call can be
+ // resolved at compile time.
+ return (*fn)(a);
+ }
+
+Marking virtual functions as ``not_tail_called`` is an error:
+
+ .. code-block:: c++
+
+ class Base {
+ public:
+ // not_tail_called on a virtual function is an error.
+ [[clang::not_tail_called]] virtual int foo1();
+
+ virtual int foo2();
+
+ // Non-virtual functions can be marked ``not_tail_called``.
+ [[clang::not_tail_called]] int foo3();
+ };
+
+ class Derived1 : public Base {
+ public:
+ int foo1() override;
+
+ // not_tail_called on a virtual function is an error.
+ [[clang::not_tail_called]] int foo2() override;
+ };
+
+
+nothrow
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``nothrow``","``gnu::nothrow``","","``nothrow``","","","Yes"
+
+Clang supports the GNU style ``__attribute__((nothrow))`` and Microsoft style
+``__declspec(nothrow)`` attribute as an equivalent of `noexcept` on function
+declarations. This attribute informs the compiler that the annotated function
+does not throw an exception. This prevents exception-unwinding. This attribute
+is particularly useful on functions in the C Standard Library that are
+guaranteed to not throw an exception.
+
+
+ns_consumed
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``ns_consumed``","``clang::ns_consumed``","``clang::ns_consumed``","","","","Yes"
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+ns_consumes_self
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``ns_consumes_self``","``clang::ns_consumes_self``","``clang::ns_consumes_self``","","","","Yes"
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+ns_returns_autoreleased
+-----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``ns_returns_autoreleased``","``clang::ns_returns_autoreleased``","``clang::ns_returns_autoreleased``","","","",""
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+ns_returns_not_retained
+-----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``ns_returns_not_retained``","``clang::ns_returns_not_retained``","``clang::ns_returns_not_retained``","","","",""
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+ns_returns_retained
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``ns_returns_retained``","``clang::ns_returns_retained``","``clang::ns_returns_retained``","","","",""
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+objc_method_family
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``objc_method_family``","``clang::objc_method_family``","``clang::objc_method_family``","","","","Yes"
+
+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.
+
+**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of
+``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This
+attribute can only be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+ - (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
+
+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 (``ns_returns_retained``,
+``ns_returns_not_retained``, etc).
+
+Query for this feature with ``__has_attribute(objc_method_family)``.
+
+
+objc_requires_super
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``objc_requires_super``","``clang::objc_requires_super``","``clang::objc_requires_super``","","","","Yes"
+
+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 ``super``" in the overriding
+method in the subclass.
+
+**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only
+be placed at the end of a method declaration:
+
+.. code-block:: objc
+
+ - (void)foo __attribute__((objc_requires_super));
+
+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
+``-dealloc`` where the call must appear at the end). It checks only that it
+exists.
+
+Note that on both OS X and iOS that the Foundation framework provides a
+convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this
+attribute:
+
+.. code-block:: objc
+
+ - (void)foo NS_REQUIRES_SUPER;
+
+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.
+
+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:
+
+.. code-block:: objc
+
+ warning: method possibly missing a [super AnnotMeth] call
+ - (void) AnnotMeth{};
+ ^
+
+
+optnone
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``optnone``","``clang::optnone``","``clang::optnone``","","","","Yes"
+
+The ``optnone`` 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.
+
+This attribute is incompatible with the ``always_inline`` and ``minsize``
+attributes.
+
+
+os_consumed
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``os_consumed``","``clang::os_consumed``","``clang::os_consumed``","","","","Yes"
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+os_consumes_this
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``os_consumes_this``","``clang::os_consumes_this``","``clang::os_consumes_this``","","","",""
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+os_returns_not_retained
+-----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``os_returns_not_retained``","``clang::os_returns_not_retained``","``clang::os_returns_not_retained``","","","","Yes"
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+os_returns_retained
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``os_returns_retained``","``clang::os_returns_retained``","``clang::os_returns_retained``","","","","Yes"
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+os_returns_retained_on_non_zero
+-------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``os_returns_retained_on_non_zero``","``clang::os_returns_retained_on_non_zero``","``clang::os_returns_retained_on_non_zero``","","","","Yes"
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+os_returns_retained_on_zero
+---------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``os_returns_retained_on_zero``","``clang::os_returns_retained_on_zero``","``clang::os_returns_retained_on_zero``","","","","Yes"
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+``+0``).
+
+It can be overriden using a family of the following attributes. In
+Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to
+a function communicates that the object is returned at ``+1``, and the caller
+is responsible for freeing it.
+Similiarly, the annotation ``__attribute__((ns_returns_not_retained))``
+specifies that the object is returned at ``+0`` and the ownership remains with
+the callee.
+The annotation ``__attribute__((ns_consumes_self))`` specifies that
+the Objective-C method call consumes the reference to ``self``, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+``__attribute__((ns_consumed))``, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+``__attribute__((cf_returns_not_retained))``,
+``__attribute__((cf_returns_retained))`` and ``__attribute__((cf_consumed))``
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+``__attribute__((os_returns_not_retained))``,
+``__attribute__((os_returns_retained))`` and ``__attribute__((os_consumed))``,
+with the same respective semantics.
+Similar to ``__attribute__((ns_consumes_self))``,
+``__attribute__((os_consumes_this))`` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with ``__attribute__((os_returns_retained))``
+or ``__attribute__((os_returns_not_retained))`` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations ``__attribute__((os_returns_retained_on_zero))``
+and ``__attribute__((os_returns_retained_on_non_zero))`` specify that
+an out parameter at ``+1`` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes ``X_returns_X_retained`` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes ``X_consumed`` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+overloadable
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``overloadable``","``clang::overloadable``","``clang::overloadable``","","","","Yes"
+
+Clang provides support for C++ function overloading in C. Function overloading
+in C is introduced using the ``overloadable`` attribute. For example, one
+might provide several overloaded versions of a ``tgsin`` function that invokes
+the appropriate standard function computing the sine of a value with ``float``,
+``double``, or ``long double`` precision:
+
+.. code-block:: c
+
+ #include <math.h>
+ float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
+ double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
+ long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
+
+Given these declarations, one can call ``tgsin`` with a ``float`` value to
+receive a ``float`` result, with a ``double`` to receive a ``double`` 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:
+
+* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a
+ floating-point promotion (per C99) rather than as a floating-point conversion
+ (as in C++).
+
+* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is
+ considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are
+ compatible types.
+
+* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T``
+ and ``U`` are compatible types. This conversion is given "conversion" rank.
+
+* If no viable candidates are otherwise available, we allow a conversion from a
+ pointer of type ``T*`` to a pointer of type ``U*``, where ``T`` and ``U`` are
+ incompatible. This conversion is ranked below all other types of conversions.
+ Please note: ``U`` lacking qualifiers that are present on ``T`` is sufficient
+ for ``T`` and ``U`` to be incompatible.
+
+The declaration of ``overloadable`` functions is restricted to function
+declarations and definitions. If a function is marked with the ``overloadable``
+attribute, then all declarations and definitions of functions with that name,
+except for at most one (see the note below about unmarked overloads), must have
+the ``overloadable`` attribute. In addition, redeclarations of a function with
+the ``overloadable`` attribute must have the ``overloadable`` attribute, and
+redeclarations of a function without the ``overloadable`` attribute must *not*
+have the ``overloadable`` attribute. e.g.,
+
+.. code-block:: c
+
+ int f(int) __attribute__((overloadable));
+ float f(float); // error: declaration of "f" must have the "overloadable" attribute
+ int f(int); // error: redeclaration of "f" must have the "overloadable" attribute
+
+ int g(int) __attribute__((overloadable));
+ int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
+
+ int h(int);
+ int h(int) __attribute__((overloadable)); // error: declaration of "h" must not
+ // have the "overloadable" attribute
+
+Functions marked ``overloadable`` must have prototypes. Therefore, the
+following code is ill-formed:
+
+.. code-block:: c
+
+ int h() __attribute__((overloadable)); // error: h does not have a prototype
+
+However, ``overloadable`` 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 ``unavailable`` attribute:
+
+.. code-block:: c++
+
+ void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
+
+Functions declared with the ``overloadable`` attribute have their names mangled
+according to the same rules as C++ function names. For example, the three
+``tgsin`` functions in our motivating example get the mangled names
+``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two
+caveats to this use of name mangling:
+
+* 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 ``static inline`` with ``overloadable``
+ functions.
+
+* The ``overloadable`` attribute has almost no meaning when used in C++,
+ because names will already be mangled and functions are already overloadable.
+ However, when an ``overloadable`` function occurs within an ``extern "C"``
+ linkage specification, it's name *will* be mangled in the same way as it
+ would in C.
+
+For the purpose of backwards compatibility, at most one function with the same
+name as other ``overloadable`` functions may omit the ``overloadable``
+attribute. In this case, the function without the ``overloadable`` attribute
+will not have its name mangled.
+
+For example:
+
+.. code-block:: c
+
+ // Notes with mangled names assume Itanium mangling.
+ int f(int);
+ int f(double) __attribute__((overloadable));
+ void foo() {
+ f(5); // Emits a call to f (not _Z1fi, as it would with an overload that
+ // was marked with overloadable).
+ f(1.0); // Emits a call to _Z1fd.
+ }
+
+Support for unmarked overloads is not present in some versions of clang. You may
+query for it using ``__has_extension(overloadable_unmarked)``.
+
+Query for this attribute with ``__has_attribute(overloadable)``.
+
+
+reinitializes
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``reinitializes``","``clang::reinitializes``","","","","",""
+
+The ``reinitializes`` attribute can be applied to a non-static, non-const C++
+member function to indicate that this member function reinitializes the entire
+object to a known state, independent of the previous state of the object.
+
+This attribute can be interpreted by static analyzers that warn about uses of an
+object that has been left in an indeterminate state by a move operation. If a
+member function marked with the ``reinitializes`` attribute is called on a
+moved-from object, the analyzer can conclude that the object is no longer in an
+indeterminate state.
+
+A typical example where this attribute would be used is on functions that clear
+a container class:
+
+.. code-block:: c++
+
+ template <class T>
+ class Container {
+ public:
+ ...
+ [[clang::reinitializes]] void Clear();
+ ...
+ };
+
+
+release_capability, release_shared_capability
+---------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``release_capability`` |br| ``release_shared_capability`` |br| ``release_generic_capability`` |br| ``unlock_function``","``clang::release_capability`` |br| ``clang::release_shared_capability`` |br| ``clang::release_generic_capability`` |br| ``clang::unlock_function``","","","","",""
+
+Marks a function as releasing a capability.
+
+
+short_call, near
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``short_call`` |br| ``near``","``gnu::short_call`` |br| ``gnu::near``","","","","","Yes"
+
+Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
+``__attribute__((short__call))``, and ``__attribute__((near))`` attributes
+on MIPS targets. These attributes may only be added to function declarations
+and change the code generated by the compiler when directly calling
+the function. The ``short_call`` and ``near`` attributes are synonyms and
+allow calls to the function to be made using the ``jal`` instruction, which
+requires the function to be located in the same naturally aligned 256MB segment
+as the caller. The ``long_call`` and ``far`` attributes are synonyms and
+require the use of a different call sequence that works regardless
+of the distance between the functions.
+
+These attributes have no effect for position-independent code.
+
+These attributes take priority over command line switches such
+as ``-mlong-calls`` and ``-mno-long-calls``.
+
+
+signal
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``signal``","``gnu::signal``","","","","","Yes"
+
+Clang supports the GNU style ``__attribute__((signal))`` attribute on
+AVR 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.
+
+Interrupt handler functions defined with the signal attribute do not re-enable interrupts.
+
+
+speculative_load_hardening
+--------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``speculative_load_hardening``","``clang::speculative_load_hardening``","``clang::speculative_load_hardening``","","","","Yes"
+
+This attribute can be applied to a function declaration in order to indicate
+ that `Speculative Load Hardening <https://llvm.org/docs/SpeculativeLoadHardening.html>`_
+ should be enabled for the function body. This can also be applied to a method
+ in Objective C. This attribute will take precedence over the command line flag in
+ the case where `-mno-speculative-load-hardening <https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-mspeculative-load-hardening>`_ is specified.
+
+ Speculative Load Hardening is a best-effort mitigation against
+ information leak attacks that make use of control flow
+ miss-speculation - specifically miss-speculation of whether a branch
+ is taken or not. Typically vulnerabilities enabling such attacks are
+ classified as "Spectre variant #1". Notably, this does not attempt to
+ mitigate against miss-speculation of branch target, classified as
+ "Spectre variant #2" vulnerabilities.
+
+ When inlining, the attribute is sticky. Inlining a function that
+ carries this attribute will cause the caller to gain the
+ attribute. This is intended to provide a maximally conservative model
+ where the code in a function annotated with this attribute will always
+ (even after inlining) end up hardened.
+
+
+target
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``target``","``gnu::target``","","","","","Yes"
+
+Clang supports the GNU style ``__attribute__((target("OPTIONS")))`` 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.
+
+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 ``arch="CPU"`` which will change the default "CPU"
+for the function.
+
+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.
+
+Additionally, this attribute supports function multiversioning for ELF based
+x86/x86-64 targets, which can be used to create multiple implementations of the
+same function that will be resolved at runtime based on the priority of their
+``target`` attribute strings. A function is considered a multiversioned function
+if either two declarations of the function have different ``target`` attribute
+strings, or if it has a ``target`` attribute string of ``default``. For
+example:
+
+ .. code-block:: c++
+
+ __attribute__((target("arch=atom")))
+ void foo() {} // will be called on 'atom' processors.
+ __attribute__((target("default")))
+ void foo() {} // will be called on any other processors.
+
+All multiversioned functions must contain a ``default`` (fallback)
+implementation, otherwise usages of the function are considered invalid.
+Additionally, a function may not become multiversioned after its first use.
+
+
+try_acquire_capability, try_acquire_shared_capability
+-----------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``try_acquire_capability`` |br| ``try_acquire_shared_capability``","``clang::try_acquire_capability`` |br| ``clang::try_acquire_shared_capability``","","","","",""
+
+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).
+
+
+xray_always_instrument, xray_never_instrument, xray_log_args
+------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``xray_always_instrument`` |br| ``xray_never_instrument``","``clang::xray_always_instrument`` |br| ``clang::xray_never_instrument``","``clang::xray_always_instrument`` |br| ``clang::xray_never_instrument``","","","","Yes"
+
+``__attribute__((xray_always_instrument))`` or ``[[clang::xray_always_instrument]]`` 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.
+
+Conversely, ``__attribute__((xray_never_instrument))`` or ``[[clang::xray_never_instrument]]`` will inhibit the insertion of these instrumentation points.
+
+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.
+
+``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is used to preserve N function arguments for the logging function. Currently, only N==1 is supported.
+
+
+xray_always_instrument, xray_never_instrument, xray_log_args
+------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``xray_log_args``","``clang::xray_log_args``","``clang::xray_log_args``","","","","Yes"
+
+``__attribute__((xray_always_instrument))`` or ``[[clang::xray_always_instrument]]`` 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.
+
+Conversely, ``__attribute__((xray_never_instrument))`` or ``[[clang::xray_never_instrument]]`` will inhibit the insertion of these instrumentation points.
+
+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.
+
+``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is used to preserve N function arguments for the logging function. Currently, only N==1 is supported.
+
+
+Variable Attributes
+===================
+
+
+always_destroy
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``always_destroy``","``clang::always_destroy``","","","","","Yes"
+
+The ``always_destroy`` attribute specifies that a variable with static or thread
+storage duration should have its exit-time destructor run. This attribute is the
+default unless clang was invoked with -fno-c++-static-destructors.
+
+
+dllexport
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``dllexport``","``gnu::dllexport``","","``dllexport``","","","Yes"
+
+The ``__declspec(dllexport)`` attribute declares a variable, function, or
+Objective-C interface to be exported from the module. It is available under the
+``-fdeclspec`` 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 dllexport_ documentation on MSDN for more
+information.
+
+.. _dllexport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx
+
+
+dllimport
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``dllimport``","``gnu::dllimport``","","``dllimport``","","","Yes"
+
+The ``__declspec(dllimport)`` attribute declares a variable, function, or
+Objective-C interface to be imported from an external module. It is available
+under the ``-fdeclspec`` 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 dllimport_ documentation on MSDN
+for more information.
+
+.. _dllimport: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx
+
+
+init_seg
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","","``init_seg``",""
+
+The attribute applied by ``pragma init_seg()`` controls the section into
+which global initialization function pointers are emitted. It is only
+available with ``-fms-extensions``. Typically, this function pointer is
+emitted into ``.CRT$XCU`` on Windows. The user can change the order of
+initialization by using a different section name with the same
+``.CRT$XC`` prefix and a suffix that sorts lexicographically before or
+after the standard ``.CRT$XCU`` sections. See the init_seg_
+documentation on MSDN for more information.
+
+.. _init_seg: http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx
+
+
+maybe_unused, unused
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``unused``","``maybe_unused`` |br| ``gnu::unused``","``maybe_unused``","","","",""
+
+When passing the ``-Wunused`` flag to Clang, entities that are unused by the
+program may be diagnosed. The ``[[maybe_unused]]`` (or
+``__attribute__((unused))``) 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 ``assert()`` statement, which makes the local variable
+unused when ``NDEBUG`` is defined.
+
+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.
+
+.. code-block: c++
+ #include <cassert>
+
+ [[maybe_unused]] void f([[maybe_unused]] bool thing1,
+ [[maybe_unused]] bool thing2) {
+ [[maybe_unused]] bool b = thing1 && thing2;
+ assert(b);
+ }
+
+
+no_destroy
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``no_destroy``","``clang::no_destroy``","","","","","Yes"
+
+The ``no_destroy`` attribute specifies that a variable with static or thread
+storage duration shouldn't have its exit-time destructor run. Annotating every
+static and thread duration variable with this attribute is equivalent to
+invoking clang with -fno-c++-static-destructors.
+
+If a variable is declared with this attribute, clang doesn't access check or
+generate the type's destructor. If you have a type that you only want to be
+annotated with ``no_destroy``, you can therefore declare the destructor private:
+
+.. code-block:: c++
+
+ struct only_no_destroy {
+ only_no_destroy();
+ private:
+ ~only_no_destroy();
+ };
+
+ [[clang::no_destroy]] only_no_destroy global; // fine!
+
+Note that destructors are still required for subobjects of aggregates annotated
+with this attribute. This is because previously constructed subobjects need to
+be destroyed if an exception gets thrown before the initialization of the
+complete object is complete. For instance:
+
+.. code-block::c++
+
+ void f() {
+ try {
+ [[clang::no_destroy]]
+ static only_no_destroy array[10]; // error, only_no_destroy has a private destructor.
+ } catch (...) {
+ // Handle the error
+ }
+ }
+
+Here, if the construction of `array[9]` fails with an exception, `array[0..8]`
+will be destroyed, so the element's destructor needs to be accessible.
+
+
+nodebug
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``nodebug``","``gnu::nodebug``","","","","","Yes"
+
+The ``nodebug`` 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.
+
+
+noescape
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``noescape``","``clang::noescape``","``clang::noescape``","","","","Yes"
+
+``noescape`` placed on a function parameter of a pointer type is used to inform
+the compiler that the pointer cannot escape: that is, no reference to the object
+the pointer points to that is derived from the parameter value will survive
+after the function returns. Users are responsible for making sure parameters
+annotated with ``noescape`` do not actuallly escape.
+
+For example:
+
+.. code-block:: c
+
+ int *gp;
+
+ void nonescapingFunc(__attribute__((noescape)) int *p) {
+ *p += 100; // OK.
+ }
+
+ void escapingFunc(__attribute__((noescape)) int *p) {
+ gp = p; // Not OK.
+ }
+
+Additionally, when the parameter is a `block pointer
+<https://clang.llvm.org/docs/BlockLanguageSpec.html>`, the same restriction
+applies to copies of the block. For example:
+
+.. code-block:: c
+
+ typedef void (^BlockTy)();
+ BlockTy g0, g1;
+
+ void nonescapingFunc(__attribute__((noescape)) BlockTy block) {
+ block(); // OK.
+ }
+
+ void escapingFunc(__attribute__((noescape)) BlockTy block) {
+ g0 = block; // Not OK.
+ g1 = Block_copy(block); // Not OK either.
+ }
+
+
+nosvm
+-----
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``nosvm``","","","","","","Yes"
+
+OpenCL 2.0 supports the optional ``__attribute__((nosvm))`` 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.
+
+Since it is not widely used and has been removed from OpenCL 2.1, it is ignored
+by Clang.
+
+
+objc_externally_retained
+------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``objc_externally_retained``","``clang::objc_externally_retained``","``clang::objc_externally_retained``","","","","Yes"
+
+The ``objc_externally_retained`` attribute can be applied to strong local
+variables, functions, methods, or blocks to opt into
+`externally-retained semantics
+<https://clang.llvm.org/docs/AutomaticReferenceCounting.html#externally-retained-variables>`_.
+
+When applied to the definition of a function, method, or block, every parameter
+of the function with implicit strong retainable object pointer type is
+considered externally-retained, and becomes ``const``. By explicitly annotating
+a parameter with ``__strong``, you can opt back into the default
+non-externally-retained behaviour for that parameter. For instance,
+``first_param`` is externally-retained below, but not ``second_param``:
+
+.. code-block:: objc
+
+ __attribute__((objc_externally_retained))
+ void f(NSArray *first_param, __strong NSArray *second_param) {
+ // ...
+ }
+
+Likewise, when applied to a strong local variable, that variable becomes
+``const`` and is considered externally-retained.
+
+When compiled without ``-fobjc-arc``, this attribute is ignored.
+
+
+pass_object_size, pass_dynamic_object_size
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``pass_object_size`` |br| ``pass_dynamic_object_size``","``clang::pass_object_size`` |br| ``clang::pass_dynamic_object_size``","``clang::pass_object_size`` |br| ``clang::pass_dynamic_object_size``","","","","Yes"
+
+.. Note:: The mangling of functions with parameters that are annotated with
+ ``pass_object_size`` is subject to change. You can get around this by
+ using ``__asm__("foo")`` to explicitly name your functions, thus preserving
+ your ABI; also, non-overloadable C functions with ``pass_object_size`` are
+ not mangled.
+
+The ``pass_object_size(Type)`` attribute can be placed on function parameters to
+instruct clang to call ``__builtin_object_size(param, Type)`` at each callsite
+of said function, and implicitly pass the result of this call in as an invisible
+argument of type ``size_t`` directly after the parameter annotated with
+``pass_object_size``. Clang will also replace any calls to
+``__builtin_object_size(param, Type)`` in the function by said implicit
+parameter.
+
+Example usage:
+
+.. code-block:: c
+
+ int bzero1(char *const p __attribute__((pass_object_size(0))))
+ __attribute__((noinline)) {
+ int i = 0;
+ for (/**/; i < (int)__builtin_object_size(p, 0); ++i) {
+ p[i] = 0;
+ }
+ return i;
+ }
+
+ int main() {
+ char chars[100];
+ int n = bzero1(&chars[0]);
+ assert(n == sizeof(chars));
+ return 0;
+ }
+
+If successfully evaluating ``__builtin_object_size(param, Type)`` at the
+callsite is not possible, then the "failed" value is passed in. So, using the
+definition of ``bzero1`` from above, the following code would exit cleanly:
+
+.. code-block:: c
+
+ int main2(int argc, char *argv[]) {
+ int n = bzero1(argv);
+ assert(n == -1);
+ return 0;
+ }
+
+``pass_object_size`` plays a part in overload resolution. If two overload
+candidates are otherwise equally good, then the overload with one or more
+parameters with ``pass_object_size`` is preferred. This implies that the choice
+between two identical overloads both with ``pass_object_size`` on one or more
+parameters will always be ambiguous; for this reason, having two such overloads
+is illegal. For example:
+
+.. code-block:: c++
+
+ #define PS(N) __attribute__((pass_object_size(N)))
+ // OK
+ void Foo(char *a, char *b); // Overload A
+ // OK -- overload A has no parameters with pass_object_size.
+ void Foo(char *a PS(0), char *b PS(0)); // Overload B
+ // Error -- Same signature (sans pass_object_size) as overload B, and both
+ // overloads have one or more parameters with the pass_object_size attribute.
+ void Foo(void *a PS(0), void *b);
+
+ // OK
+ void Bar(void *a PS(0)); // Overload C
+ // OK
+ void Bar(char *c PS(1)); // Overload D
+
+ void main() {
+ char known[10], *unknown;
+ Foo(unknown, unknown); // Calls overload B
+ Foo(known, unknown); // Calls overload B
+ Foo(unknown, known); // Calls overload B
+ Foo(known, known); // Calls overload B
+
+ Bar(known); // Calls overload D
+ Bar(unknown); // Calls overload D
+ }
+
+Currently, ``pass_object_size`` is a bit restricted in terms of its usage:
+
+* Only one use of ``pass_object_size`` is allowed per parameter.
+
+* It is an error to take the address of a function with ``pass_object_size`` on
+ any of its parameters. If you wish to do this, you can create an overload
+ without ``pass_object_size`` on any parameters.
+
+* It is an error to apply the ``pass_object_size`` attribute to parameters that
+ are not pointers. Additionally, any parameter that ``pass_object_size`` is
+ applied to must be marked ``const`` at its function's definition.
+
+Clang also supports the ``pass_dynamic_object_size`` attribute, which behaves
+identically to ``pass_object_size``, but evaluates a call to
+``__builtin_dynamic_object_size`` at the callee instead of
+``__builtin_object_size``. ``__builtin_dynamic_object_size`` provides some extra
+runtime checks when the object size can't be determined at compile-time. You can
+read more about ``__builtin_dynamic_object_size`` `here
+<https://clang.llvm.org/docs/LanguageExtensions.html#evaluating-object-size-dynamically>`_.
+
+
+require_constant_initialization
+-------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``require_constant_initialization``","``clang::require_constant_initialization``","","","","","Yes"
+
+This attribute specifies that the variable to which it is attached is intended
+to have a `constant initializer <http://en.cppreference.com/w/cpp/language/constant_initialization>`_
+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++.
+
+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.
+
+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.
+
+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.
+
+.. code-block:: c++
+
+ // -std=c++14
+ #define SAFE_STATIC [[clang::require_constant_initialization]]
+ struct T {
+ constexpr T(int) {}
+ ~T(); // non-trivial
+ };
+ SAFE_STATIC T x = {42}; // Initialization OK. Doesn't check destructor.
+ SAFE_STATIC T y = 42; // error: variable does not have a constant initializer
+ // copy initialization is not a constant expression on a non-literal type.
+
+
+section, __declspec(allocate)
+-----------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``section``","``gnu::section``","","``allocate``","","","Yes"
+
+The ``section`` attribute allows you to specify a specific section a
+global variable or function should be in after translation.
+
+
+swift_context
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``swift_context``","``clang::swift_context``","``clang::swift_context``","","","","Yes"
+
+The ``swift_context`` attribute marks a parameter of a ``swiftcall``
+function as having the special context-parameter ABI treatment.
+
+This treatment generally passes the context value in a special register
+which is normally callee-preserved.
+
+A ``swift_context`` parameter must either be the last parameter or must be
+followed by a ``swift_error_result`` parameter (which itself must always be
+the last parameter).
+
+A context parameter must have pointer or reference type.
+
+
+swift_error_result
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``swift_error_result``","``clang::swift_error_result``","``clang::swift_error_result``","","","","Yes"
+
+The ``swift_error_result`` attribute marks a parameter of a ``swiftcall``
+function as having the special error-result ABI treatment.
+
+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:
+
+- 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.
+
+- 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.
+
+A ``swift_error_result`` parameter must be the last parameter, and it must be
+preceded by a ``swift_context`` parameter.
+
+A ``swift_error_result`` parameter must have type ``T**`` or ``T*&`` for some
+type T. Note that no qualifiers are permitted on the intermediate level.
+
+It is undefined behavior if the caller does not pass a pointer or
+reference to a valid object.
+
+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.
+
+
+swift_indirect_result
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``swift_indirect_result``","``clang::swift_indirect_result``","``clang::swift_indirect_result``","","","","Yes"
+
+The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall``
+function as having the special indirect-result ABI treatment.
+
+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
+``swift_indirect_result`` parameters.
+
+A ``swift_indirect_result`` parameter must either be the first parameter or
+follow another ``swift_indirect_result`` parameter.
+
+A ``swift_indirect_result`` parameter must have type ``T*`` or ``T&`` for
+some object type ``T``. If ``T`` 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 ``T``.
+
+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).
+
+
+swiftcall
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``swiftcall``","``clang::swiftcall``","``clang::swiftcall``","","","",""
+
+The ``swiftcall`` attribute indicates that a function should be called
+using the Swift calling convention for a function or function pointer.
+
+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 ``swiftcall`` convention only handles this second phase of
+lowering; the C function type must accurately reflect the results
+of the first phase, as follows:
+
+- Results classified as indirect by high-level lowering should be
+ represented as parameters with the ``swift_indirect_result`` attribute.
+
+- Results classified as direct by high-level lowering should be represented
+ as follows:
+
+ - First, remove any empty direct results.
+
+ - If there are no direct results, the C result type should be ``void``.
+
+ - If there is one direct result, the C result type should be a type with
+ the exact layout of that result type.
+
+ - 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.
+
+- Parameters classified as indirect by high-level lowering should be
+ represented as parameters of pointer type.
+
+- 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.
+
+- The context parameter, if present, should be represented as a trailing
+ parameter with the ``swift_context`` attribute.
+
+- The error result parameter, if present, should be represented as a
+ trailing parameter (always following a context parameter) with the
+ ``swift_error_result`` attribute.
+
+``swiftcall`` does not support variadic arguments or unprototyped functions.
+
+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.
+
+Support for this feature is target-dependent, although it should be
+supported on every target that Swift supports. Query for this support
+with ``__has_attribute(swiftcall)``. This implies support for the
+``swift_context``, ``swift_error_result``, and ``swift_indirect_result``
+attributes.
+
+
+thread
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","``thread``","","",""
+
+The ``__declspec(thread)`` attribute declares a variable with thread local
+storage. It is available under the ``-fms-extensions`` flag for MSVC
+compatibility. See the documentation for `__declspec(thread)`_ on MSDN.
+
+.. _`__declspec(thread)`: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx
+
+In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the
+GNU ``__thread`` 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.
+
+
+tls_model
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``tls_model``","``gnu::tls_model``","","","","","Yes"
+
+The ``tls_model`` attribute allows you to specify which thread-local storage
+model to use. It accepts the following strings:
+
+* global-dynamic
+* local-dynamic
+* initial-exec
+* local-exec
+
+TLS models are mutually exclusive.
+
+
+uninitialized
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``uninitialized``","``clang::uninitialized``","","","","",""
+
+The command-line parameter ``-ftrivial-auto-var-init=*`` can be used to
+initialize trivial automatic stack variables. By default, trivial automatic
+stack variables are uninitialized. This attribute is used to override the
+command-line parameter, forcing variables to remain uninitialized. It has no
+semantic meaning in that using uninitialized values is undefined behavior,
+it rather documents the programmer's intent.
+
+
+Field Attributes
+================
+
+
+no_unique_address
+-----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","``no_unique_address``","","","","",""
+
+The ``no_unique_address`` attribute allows tail padding in a non-static data
+member to overlap other members of the enclosing class (and in the special
+case when the type is empty, permits it to fully overlap other members).
+The field is laid out as if a base class were encountered at the corresponding
+point within the class (except that it does not share a vptr with the enclosing
+object).
+
+Example usage:
+
+.. code-block:: c++
+
+ template<typename T, typename Alloc> struct my_vector {
+ T *p;
+ [[no_unique_address]] Alloc alloc;
+ // ...
+ };
+ static_assert(sizeof(my_vector<int, std::allocator<int>>) == sizeof(int*));
+
+``[[no_unique_address]]`` is a standard C++20 attribute. Clang supports its use
+in C++11 onwards.
+
+
+Type Attributes
+===============
+
+
+align_value
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``align_value``","","","","","","Yes"
+
+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.
+
+ .. code-block:: c
+
+ typedef double * aligned_double_ptr __attribute__((align_value(64)));
+ void foo(double & x __attribute__((align_value(128)),
+ aligned_double_ptr y) { ... }
+
+If the pointer value does not have the specified alignment at runtime, the
+behavior of the program is undefined.
+
+
+hip_pinned_shadow
+-----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``hip_pinned_shadow``","","","``__hip_pinned_shadow__``","","","Yes"
+
+The GNU style attribute __attribute__((hip_pinned_shadow)) or MSVC style attribute
+__declspec(hip_pinned_shadow) can be added to the definition of a global variable
+to indicate it is a HIP pinned shadow variable. A HIP pinned shadow variable can
+be accessed on both device side and host side. It has external linkage and is
+not initialized on device side. It has internal linkage and is initialized by
+the initializer on host side.
+
+
+noderef
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``noderef``","``clang::noderef``","``clang::noderef``","","","",""
+
+The ``noderef`` attribute causes clang to diagnose dereferences of annotated pointer types.
+This is ideally used with pointers that point to special memory which cannot be read
+from or written to, but allowing for the pointer to be used in pointer arithmetic.
+The following are examples of valid expressions where dereferences are diagnosed:
+
+.. code-block:: c
+
+ int __attribute__((noderef)) *p;
+ int x = *p; // warning
+
+ int __attribute__((noderef)) **p2;
+ x = **p2; // warning
+
+ int * __attribute__((noderef)) *p3;
+ p = *p3; // warning
+
+ struct S {
+ int a;
+ };
+ struct S __attribute__((noderef)) *s;
+ x = s->a; // warning
+ x = (*s).a; // warning
+
+Not all dereferences may diagnose a warning if the value directed by the pointer may not be
+accessed. The following are examples of valid expressions where may not be diagnosed:
+
+.. code-block:: c
+
+ int *q;
+ int __attribute__((noderef)) *p;
+ q = &*p;
+ q = *&p;
+
+ struct S {
+ int a;
+ };
+ struct S __attribute__((noderef)) *s;
+ p = &s->a;
+ p = &(*s).a;
+
+``noderef`` is currently only supported for pointers and arrays and not usable for
+references or Objective-C object pointers.
+
+.. code-block: c++
+
+ int x = 2;
+ int __attribute__((noderef)) &y = x; // warning: 'noderef' can only be used on an array or pointer type
+
+.. code-block: objc
+
+ id __attribute__((noderef)) obj = [NSObject new]; // warning: 'noderef' can only be used on an array or pointer type
+
+
+objc_class_stub
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``objc_class_stub``","``clang::objc_class_stub``","``clang::objc_class_stub``","","","","Yes"
+
+This attribute specifies that the Objective-C class to which it applies is
+instantiated at runtime.
+
+Unlike ``__attribute__((objc_runtime_visible))``, a class having this attribute
+still has a "class stub" that is visible to the linker. This allows categories
+to be defined. Static message sends with the class as a receiver use a special
+access pattern to ensure the class is lazily instantiated from the class stub.
+
+Classes annotated with this attribute cannot be subclassed and cannot have
+implementations defined for them. This attribute is intended for use in
+Swift-generated headers for classes defined in Swift.
+
+Adding or removing this attribute to a class is an ABI-breaking change.
+
+
+Statement Attributes
+====================
+
+
+#pragma clang loop
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","","``clang loop`` |br| ``unroll`` |br| ``nounroll`` |br| ``unroll_and_jam`` |br| ``nounroll_and_jam``",""
+
+The ``#pragma clang loop`` directive allows loop optimization hints to be
+specified for the subsequent loop. The directive allows pipelining to be
+disabled, or vectorization, interleaving, and unrolling to be enabled or disabled.
+Vector width, interleave count, unrolling count, and the initiation interval
+for pipelining can be explicitly specified. See `language extensions
+<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
+for details.
+
+
+#pragma unroll, #pragma nounroll
+--------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","","``clang loop`` |br| ``unroll`` |br| ``nounroll`` |br| ``unroll_and_jam`` |br| ``nounroll_and_jam``",""
+
+Loop unrolling optimization hints can be specified with ``#pragma unroll`` and
+``#pragma nounroll``. The pragma is placed immediately before a for, while,
+do-while, or c++11 range-based for loop.
+
+Specifying ``#pragma unroll`` 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:
+
+.. code-block:: c++
+
+ #pragma unroll
+ for (...) {
+ ...
+ }
+
+Specifying the optional parameter, ``#pragma unroll _value_``, directs the
+unroller to unroll the loop ``_value_`` times. The parameter may optionally be
+enclosed in parentheses:
+
+.. code-block:: c++
+
+ #pragma unroll 16
+ for (...) {
+ ...
+ }
+
+ #pragma unroll(16)
+ for (...) {
+ ...
+ }
+
+Specifying ``#pragma nounroll`` indicates that the loop should not be unrolled:
+
+.. code-block:: c++
+
+ #pragma nounroll
+ for (...) {
+ ...
+ }
+
+``#pragma unroll`` and ``#pragma unroll _value_`` have identical semantics to
+``#pragma clang loop unroll(full)`` and
+``#pragma clang loop unroll_count(_value_)`` respectively. ``#pragma nounroll``
+is equivalent to ``#pragma clang loop unroll(disable)``. See
+`language extensions
+<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_
+for further details including limitations of the unroll hints.
+
+
+__read_only, __write_only, __read_write (read_only, write_only, read_write)
+---------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``__read_only`` |br| ``read_only`` |br| ``__write_only`` |br| ``write_only`` |br| ``__read_write`` |br| ``read_write``","",""
+
+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.
+
+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.
+
+.. code-block:: c
+
+ kernel void
+ foo (read_only image2d_t imageA,
+ write_only image2d_t imageB) {
+ ...
+ }
+
+In the above example imageA is a read-only 2D image object, and imageB is a
+write-only 2D image object.
+
+The read_write (or __read_write) qualifier can not be used with pipe.
+
+More details can be found in the OpenCL C language Spec v2.0, Section 6.6.
+
+
+fallthrough
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","``fallthrough`` |br| ``clang::fallthrough``","``fallthrough``","","","",""
+
+The ``fallthrough`` (or ``clang::fallthrough``) 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 ``break;``, so it can be placed in most places
+where ``break;`` can, but only if there are no statements on the execution path
+between it and the next switch label.
+
+By default, Clang does not warn on unannotated fallthrough from one ``switch``
+case to another. Diagnostics on fallthrough without a corresponding annotation
+can be enabled with the ``-Wimplicit-fallthrough`` argument.
+
+Here is an example:
+
+.. code-block:: c++
+
+ // compile with -Wimplicit-fallthrough
+ switch (n) {
+ case 22:
+ case 33: // no warning: no statements between case labels
+ f();
+ case 44: // warning: unannotated fall-through
+ g();
+ [[clang::fallthrough]];
+ case 55: // no warning
+ if (x) {
+ h();
+ break;
+ }
+ else {
+ i();
+ [[clang::fallthrough]];
+ }
+ case 66: // no warning
+ p();
+ [[clang::fallthrough]]; // warning: fallthrough annotation does not
+ // directly precede case label
+ q();
+ case 77: // warning: unannotated fall-through
+ r();
+ }
+
+
+intel_reqd_sub_group_size
+-------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``intel_reqd_sub_group_size``","","","","","","Yes"
+
+The optional attribute intel_reqd_sub_group_size can be used to indicate that
+the kernel must be compiled and executed with the specified subgroup size. When
+this attribute is present, get_max_sub_group_size() is guaranteed to return the
+specified integer value. This is important for the correctness of many subgroup
+algorithms, and in some cases may be used by the compiler to generate more optimal
+code. See `cl_intel_required_subgroup_size
+<https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_required_subgroup_size.txt>`
+for details.
+
+
+opencl_unroll_hint
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``opencl_unroll_hint``","","","","","",""
+
+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
+`OpenCL v2.0 <https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf>`_
+s6.11.5 for details.
+
+
+suppress
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","``gsl::suppress``","","","","",""
+
+The ``[[gsl::suppress]]`` attribute suppresses specific
+clang-tidy diagnostics for rules of the `C++ Core Guidelines`_ in a portable
+way. The attribute can be attached to declarations, statements, and at
+namespace scope.
+
+.. code-block:: c++
+
+ [[gsl::suppress("Rh-public")]]
+ void f_() {
+ int *p;
+ [[gsl::suppress("type")]] {
+ p = reinterpret_cast<int*>(7);
+ }
+ }
+ namespace N {
+ [[clang::suppress("type", "bounds")]];
+ ...
+ }
+
+.. _`C++ Core Guidelines`: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#inforce-enforcement
+
+
+Declaration Attributes
+======================
+
+
+__single_inhertiance, __multiple_inheritance, __virtual_inheritance
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``__single_inheritance`` |br| ``__multiple_inheritance`` |br| ``__virtual_inheritance`` |br| ``__unspecified_inheritance``","",""
+
+This collection of keywords is enabled under ``-fms-extensions`` and controls
+the pointer-to-member representation used on ``*-*-win32`` targets.
+
+The ``*-*-win32`` targets utilize a pointer-to-member representation which
+varies in size and alignment depending on the definition of the underlying
+class.
+
+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.
+
+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.
+
+This family of keywords belong between the ``class-key`` and ``class-name``:
+
+.. code-block:: c++
+
+ struct __single_inheritance S;
+ int S::*i;
+ struct S {};
+
+This keyword can be applied to class templates but only has an effect when used
+on full specializations:
+
+.. code-block:: c++
+
+ template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template
+ template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization
+ template <> struct __single_inheritance A<int, float>;
+
+Note that choosing an inheritance model less general than strictly necessary is
+an error:
+
+.. code-block:: c++
+
+ struct __multiple_inheritance S; // error: inheritance model does not match definition
+ int S::*i;
+ struct S {};
+
+
+deprecated
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``deprecated``","``gnu::deprecated`` |br| ``deprecated``","``deprecated``","``deprecated``","","",""
+
+The ``deprecated`` 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.
+
+Consider the function declaration for a hypothetical function ``f``:
+
+.. code-block:: c++
+
+ void f(void) __attribute__((deprecated("message", "replacement")));
+
+When spelled as `__attribute__((deprecated))`, 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
+`[[gnu::deprecated]] or [[deprecated]]`, the attribute can have one optional
+string argument which is the message to display when emitting the warning.
+
+
+empty_bases
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","``empty_bases``","","",""
+
+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.
+
+
+enum_extensibility
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``enum_extensibility``","``clang::enum_extensibility``","``clang::enum_extensibility``","","","","Yes"
+
+Attribute ``enum_extensibility`` is used to distinguish between enum definitions
+that are extensible and those that are not. The attribute can take either
+``closed`` or ``open`` as an argument. ``closed`` indicates a variable of the
+enum type takes a value that corresponds to one of the enumerators listed in the
+enum definition or, when the enum is annotated with ``flag_enum``, a value that
+can be constructed using values corresponding to the enumerators. ``open``
+indicates a variable of the enum type can take any values allowed by the
+standard and instructs clang to be more lenient when issuing warnings.
+
+.. code-block:: c
+
+ enum __attribute__((enum_extensibility(closed))) ClosedEnum {
+ A0, A1
+ };
+
+ enum __attribute__((enum_extensibility(open))) OpenEnum {
+ B0, B1
+ };
+
+ enum __attribute__((enum_extensibility(closed),flag_enum)) ClosedFlagEnum {
+ C0 = 1 << 0, C1 = 1 << 1
+ };
+
+ enum __attribute__((enum_extensibility(open),flag_enum)) OpenFlagEnum {
+ D0 = 1 << 0, D1 = 1 << 1
+ };
+
+ void foo1() {
+ enum ClosedEnum ce;
+ enum OpenEnum oe;
+ enum ClosedFlagEnum cfe;
+ enum OpenFlagEnum ofe;
+
+ ce = A1; // no warnings
+ ce = 100; // warning issued
+ oe = B1; // no warnings
+ oe = 100; // no warnings
+ cfe = C0 | C1; // no warnings
+ cfe = C0 | C1 | 4; // warning issued
+ ofe = D0 | D1; // no warnings
+ ofe = D0 | D1 | 4; // no warnings
+ }
+
+
+external_source_symbol
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``external_source_symbol``","``clang::external_source_symbol``","``clang::external_source_symbol``","","","","Yes"
+
+The ``external_source_symbol`` attribute specifies that a declaration originates
+from an external source and describes the nature of that source.
+
+The fact that Clang is capable of recognizing declarations that were defined
+externally can be used to provide better tooling support for mixed-language
+projects or projects that rely on auto-generated code. For instance, an IDE that
+uses Clang and that supports mixed-language projects can use this attribute to
+provide a correct 'jump-to-definition' feature. For a concrete example,
+consider a protocol that's defined in a Swift file:
+
+.. code-block:: swift
+
+ @objc public protocol SwiftProtocol {
+ func method()
+ }
+
+This protocol can be used from Objective-C code by including a header file that
+was generated by the Swift compiler. The declarations in that header can use
+the ``external_source_symbol`` attribute to make Clang aware of the fact
+that ``SwiftProtocol`` actually originates from a Swift module:
+
+.. code-block:: objc
+
+ __attribute__((external_source_symbol(language="Swift",defined_in="module")))
+ @protocol SwiftProtocol
+ @required
+ - (void) method;
+ @end
+
+Consequently, when 'jump-to-definition' is performed at a location that
+references ``SwiftProtocol``, the IDE can jump to the original definition in
+the Swift source file rather than jumping to the Objective-C declaration in the
+auto-generated header file.
+
+The ``external_source_symbol`` attribute is a comma-separated list that includes
+clauses that describe the origin and the nature of the particular declaration.
+Those clauses can be:
+
+language=\ *string-literal*
+ The name of the source language in which this declaration was defined.
+
+defined_in=\ *string-literal*
+ The name of the source container in which the declaration was defined. The
+ exact definition of source container is language-specific, e.g. Swift's
+ source containers are modules, so ``defined_in`` should specify the Swift
+ module name.
+
+generated_declaration
+ This declaration was automatically generated by some tool.
+
+The clauses can be specified in any order. The clauses that are listed above are
+all optional, but the attribute has to have at least one clause.
+
+
+flag_enum
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``flag_enum``","``clang::flag_enum``","``clang::flag_enum``","","","","Yes"
+
+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.
+
+
+layout_version
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","``layout_version``","","",""
+
+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.
+
+
+lto_visibility_public
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``lto_visibility_public``","``clang::lto_visibility_public``","``clang::lto_visibility_public``","","","","Yes"
+
+See :doc:`LTOVisibility`.
+
+
+novtable
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","``novtable``","","",""
+
+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.
+
+
+objc_boxable
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``objc_boxable``","``clang::objc_boxable``","``clang::objc_boxable``","","","","Yes"
+
+Structs and unions marked with the ``objc_boxable`` attribute can be used
+with the Objective-C boxed expression syntax, ``@(...)``.
+
+**Usage**: ``__attribute__((objc_boxable))``. This attribute
+can only be placed on a declaration of a trivially-copyable struct or union:
+
+.. code-block:: objc
+
+ 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);
+
+
+objc_nonlazy_class
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``objc_nonlazy_class``","``clang::objc_nonlazy_class``","``clang::objc_nonlazy_class``","","","","Yes"
+
+This attribute can be added to an Objective-C ``@interface`` or
+``@implementation`` declaration to add the class to the list of non-lazily
+initialized classes. A non-lazy class will be initialized eagerly when the
+Objective-C runtime is loaded. This is required for certain system classes which
+have instances allocated in non-standard ways, such as the classes for blocks
+and constant strings. Adding this attribute is essentially equivalent to
+providing a trivial `+load` method but avoids the (fairly small) load-time
+overheads associated with defining and calling such a method.
+
+
+objc_runtime_name
+-----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``objc_runtime_name``","``clang::objc_runtime_name``","``clang::objc_runtime_name``","","","","Yes"
+
+By default, the Objective-C interface or protocol identifier is used
+in the metadata name for that object. The `objc_runtime_name`
+attribute allows annotated interfaces or protocols to use the
+specified string argument in the object's metadata name instead of the
+default name.
+
+**Usage**: ``__attribute__((objc_runtime_name("MyLocalName")))``. This attribute
+can only be placed before an @protocol or @interface declaration:
+
+.. code-block:: objc
+
+ __attribute__((objc_runtime_name("MyLocalName")))
+ @interface Message
+ @end
+
+
+objc_runtime_visible
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``objc_runtime_visible``","``clang::objc_runtime_visible``","``clang::objc_runtime_visible``","","","","Yes"
+
+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.
+
+
+objc_subclassing_restricted
+---------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``objc_subclassing_restricted``","``clang::objc_subclassing_restricted``","``clang::objc_subclassing_restricted``","","","","Yes"
+
+This attribute can be added to an Objective-C ``@interface`` declaration to
+ensure that this class cannot be subclassed.
+
+
+selectany
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``selectany``","``gnu::selectany``","","``selectany``","","",""
+
+This attribute appertains to a global symbol, causing it to have a weak
+definition (
+`linkonce <https://llvm.org/docs/LangRef.html#linkage-types>`_
+), allowing the linker to select any definition.
+
+For more information see
+`gcc documentation <https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html>`_
+or `msvc documentation <https://docs.microsoft.com/pl-pl/cpp/cpp/selectany>`_.
+
+
+transparent_union
+-----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``transparent_union``","``gnu::transparent_union``","","","","",""
+
+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:
+
+- A value whose type is any member of the transparent union can be passed as an
+ argument without the need to cast that value.
+
+- 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.
+
+Transparent unions are not supported in C++.
+
+
+trivial_abi
+-----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``trivial_abi``","``clang::trivial_abi``","","","","","Yes"
+
+The ``trivial_abi`` attribute can be applied to a C++ class, struct, or union.
+It instructs the compiler to pass and return the type using the C ABI for the
+underlying type when the type would otherwise be considered non-trivial for the
+purpose of calls.
+A class annotated with `trivial_abi` can have non-trivial destructors or copy/move constructors without automatically becoming non-trivial for the purposes of calls. For example:
+
+ .. code-block:: c++
+
+ // A is trivial for the purposes of calls because `trivial_abi` makes the
+ // user-provided special functions trivial.
+ struct __attribute__((trivial_abi)) A {
+ ~A();
+ A(const A &);
+ A(A &&);
+ int x;
+ };
+
+ // B's destructor and copy/move constructor are considered trivial for the
+ // purpose of calls because A is trivial.
+ struct B {
+ A a;
+ };
+
+If a type is trivial for the purposes of calls, has a non-trivial destructor,
+and is passed as an argument by value, the convention is that the callee will
+destroy the object before returning.
+
+Attribute ``trivial_abi`` has no effect in the following cases:
+
+- The class directly declares a virtual base or virtual methods.
+- The class has a base class that is non-trivial for the purposes of calls.
+- The class has a non-static data member whose type is non-trivial for the purposes of calls, which includes:
+
+ - classes that are non-trivial for the purposes of calls
+ - __weak-qualified types in Objective-C++
+ - arrays of any of the above
+
+
+OpenCL Address Spaces
+=====================
+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).
+
+ .. code-block:: c
+
+ __constant int c = ...;
+
+ __generic int* foo(global int* g) {
+ __local int* l;
+ private int p;
+ ...
+ return l;
+ }
+
+More details can be found in the OpenCL C language Spec v2.0, Section 6.5.
+
+constant
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``__constant`` |br| ``constant``","",""
+
+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.
+
+
+generic
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``__generic`` |br| ``generic``","",""
+
+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.
+
+
+global
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``__global`` |br| ``global``","",""
+
+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.
+
+
+local
+-----
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``__local`` |br| ``local``","",""
+
+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.
+
+
+private
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``__private`` |br| ``private``","",""
+
+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.
+
+
+AMD GPU Attributes
+==================
+
+
+amdgpu_flat_work_group_size
+---------------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``amdgpu_flat_work_group_size``","``clang::amdgpu_flat_work_group_size``","","","","","Yes"
+
+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.
+
+Clang supports the
+``__attribute__((amdgpu_flat_work_group_size(<min>, <max>)))`` attribute for the
+AMDGPU target. This attribute may be attached to a kernel function definition
+and is an optimization hint.
+
+``<min>`` parameter specifies the minimum flat work-group size, and ``<max>``
+parameter specifies the maximum flat work-group size (must be greater than
+``<min>``) to which all dispatches of the kernel will conform. Passing ``0, 0``
+as ``<min>, <max>`` implies the default behavior (``128, 256``).
+
+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.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes.
+
+
+amdgpu_num_sgpr
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``amdgpu_num_sgpr``","``clang::amdgpu_num_sgpr``","","","","","Yes"
+
+Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
+``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.
+
+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 ``0`` as
+``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
+
+These attributes can be used to test the AMDGPU target backend. It is
+recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+ - The AMDGPU target backend is unable to create machine code that can meet the
+ request.
+
+
+amdgpu_num_vgpr
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``amdgpu_num_vgpr``","``clang::amdgpu_num_vgpr``","","","","","Yes"
+
+Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
+``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.
+
+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 ``0`` as
+``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
+
+These attributes can be used to test the AMDGPU target backend. It is
+recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+ - The AMDGPU target backend is unable to create machine code that can meet the
+ request.
+
+
+amdgpu_waves_per_eu
+-------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``amdgpu_waves_per_eu``","``clang::amdgpu_waves_per_eu``","","","","","Yes"
+
+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.
+
+Clang supports the ``__attribute__((amdgpu_waves_per_eu(<min>[, <max>])))``
+attribute for the AMDGPU target. This attribute may be attached to a kernel
+function definition and is an optimization hint.
+
+``<min>`` parameter specifies the requested minimum number of waves per EU, and
+*optional* ``<max>`` parameter specifies the requested maximum number of waves
+per EU (must be greater than ``<min>`` if specified). If ``<max>`` 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
+``0, 0`` as ``<min>, <max>`` implies the default behavior (no limits).
+
+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 ``<min>`` wavefronts and at most
+``<max>`` 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.
+
+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.
+
+An error will be given if:
+ - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+ - The AMDGPU target backend is unable to create machine code that can meet the
+ request.
+
+
+Calling Conventions
+===================
+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.
+
+aarch64_vector_pcs
+------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``aarch64_vector_pcs``","``clang::aarch64_vector_pcs``","``clang::aarch64_vector_pcs``","","","",""
+
+On AArch64 targets, this attribute changes the calling convention of a
+function to preserve additional floating-point and Advanced SIMD registers
+relative to the default calling convention used for AArch64.
+
+This means it is more efficient to call such functions from code that performs
+extensive floating-point and vector calculations, because fewer live SIMD and FP
+registers need to be saved. This property makes it well-suited for e.g.
+floating-point or vector math library functions, which are typically leaf
+functions that require a small number of registers.
+
+However, using this attribute also means that it is more expensive to call
+a function that adheres to the default calling convention from within such
+a function. Therefore, it is recommended that this attribute is only used
+for leaf functions.
+
+For more information, see the documentation for `aarch64_vector_pcs`_ on
+the Arm Developer website.
+
+.. _`aarch64_vector_pcs`: https://developer.arm.com/products/software-development-tools/hpc/arm-compiler-for-hpc/vector-function-abi
+
+
+fastcall
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``fastcall``","``gnu::fastcall``","","","``__fastcall`` |br| ``_fastcall``","",""
+
+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 ``regparm`` attribute, which does
+not require callee-cleanup. See the documentation for `__fastcall`_ on MSDN.
+
+.. _`__fastcall`: http://msdn.microsoft.com/en-us/library/6xa169sk.aspx
+
+
+ms_abi
+------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``ms_abi``","``gnu::ms_abi``","","","","",""
+
+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.
+
+
+pcs
+---
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``pcs``","``gnu::pcs``","","","","",""
+
+On ARM targets, this attribute can be used to select calling conventions
+similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and
+"aapcs-vfp".
+
+
+preserve_all
+------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``preserve_all``","``clang::preserve_all``","``clang::preserve_all``","","","",""
+
+On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The ``preserve_all`` calling convention attempts to make the code
+in the caller even less intrusive than the ``preserve_most`` calling convention.
+This calling convention also behaves identical to the ``C`` 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.
+
+- 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).
+
+The idea behind this convention is to support calls to runtime functions
+that don't need to call out to any other functions.
+
+This calling convention, like the ``preserve_most`` calling convention, will be
+used by a future version of the Objective-C runtime and should be considered
+experimental at this time.
+
+
+preserve_most
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``preserve_most``","``clang::preserve_most``","``clang::preserve_most``","","","",""
+
+On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The ``preserve_most`` calling convention attempts to make the code
+in the caller as unintrusive as possible. This convention behaves identically
+to the ``C`` 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.
+
+- 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.
+
+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
+`preserve_most` calling convention is very similar to the ``cold`` calling
+convention in terms of caller/callee-saved registers, but they are used for
+different types of function calls. ``coldcc`` is for function calls that are
+rarely executed, whereas `preserve_most` function calls are intended to be
+on the hot path and definitely executed a lot. Furthermore ``preserve_most``
+doesn't prevent the inliner from inlining the function call.
+
+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.
+
+
+regcall
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``regcall``","``gnu::regcall``","","","``__regcall``","",""
+
+On x86 targets, this attribute changes the calling convention to
+`__regcall`_ 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.
+
+.. _`__regcall`: https://software.intel.com/en-us/node/693069
+
+
+regparm
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``regparm``","``gnu::regparm``","","","","",""
+
+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.
+
+
+stdcall
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``stdcall``","``gnu::stdcall``","","","``__stdcall`` |br| ``_stdcall``","",""
+
+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 `__stdcall`_ on MSDN.
+
+.. _`__stdcall`: http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx
+
+
+thiscall
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``thiscall``","``gnu::thiscall``","","","``__thiscall`` |br| ``_thiscall``","",""
+
+On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX for the first parameter (typically the implicit ``this``
+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 `__thiscall`_ on
+MSDN.
+
+.. _`__thiscall`: http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx
+
+
+vectorcall
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``vectorcall``","``clang::vectorcall``","``clang::vectorcall``","","``__vectorcall`` |br| ``_vectorcall``","",""
+
+On 32-bit x86 *and* x86_64 targets, this attribute changes the calling
+convention of a function to pass vector parameters in SSE registers.
+
+On 32-bit x86 targets, this calling convention is similar to ``__fastcall``.
+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 *not* clear the stack, and integer parameters are
+passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling
+convention.
+
+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.
+
+See the documentation for `__vectorcall`_ on MSDN for more details.
+
+.. _`__vectorcall`: http://msdn.microsoft.com/en-us/library/dn375768.aspx
+
+
+Consumed Annotation Checking
+============================
+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 **the implementation
+for these annotations is currently in development and are subject to change.**
+
+callable_when
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``callable_when``","``clang::callable_when``","","","","","Yes"
+
+Use ``__attribute__((callable_when(...)))`` 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.:
+
+``__attribute__((callable_when("unconsumed", "unknown")))``
+
+
+consumable
+----------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``consumable``","``clang::consumable``","","","","","Yes"
+
+Each ``class`` that uses any of the typestate annotations must first be marked
+using the ``consumable`` attribute. Failure to do so will result in a warning.
+
+This attribute accepts a single parameter that must be one of the following:
+``unknown``, ``consumed``, or ``unconsumed``.
+
+
+param_typestate
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``param_typestate``","``clang::param_typestate``","","","","","Yes"
+
+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.
+
+
+return_typestate
+----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``return_typestate``","``clang::return_typestate``","","","","","Yes"
+
+The ``return_typestate`` 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.
+
+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.
+
+
+set_typestate
+-------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``set_typestate``","``clang::set_typestate``","","","","","Yes"
+
+Annotate methods that transition an object into a new state with
+``__attribute__((set_typestate(new_state)))``. The new state must be
+unconsumed, consumed, or unknown.
+
+
+test_typestate
+--------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``test_typestate``","``clang::test_typestate``","","","","","Yes"
+
+Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method
+returns true if the object is in the specified state..
+
+
+Type Safety Checking
+====================
+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:
+
+* MPI library implementations, where these attributes enable checking that
+ the buffer type matches the passed ``MPI_Datatype``;
+* for HDF5 library there is a similar use case to MPI;
+* checking types of variadic functions' arguments for functions like
+ ``fcntl()`` and ``ioctl()``.
+
+You can detect support for these attributes with ``__has_attribute()``. For
+example:
+
+.. code-block:: c++
+
+ #if defined(__has_attribute)
+ # if __has_attribute(argument_with_type_tag) && \
+ __has_attribute(pointer_with_type_tag) && \
+ __has_attribute(type_tag_for_datatype)
+ # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
+ /* ... other macros ... */
+ # endif
+ #endif
+
+ #if !defined(ATTR_MPI_PWT)
+ # define ATTR_MPI_PWT(buffer_idx, type_idx)
+ #endif
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ ATTR_MPI_PWT(1,3);
+
+argument_with_type_tag
+----------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``argument_with_type_tag`` |br| ``pointer_with_type_tag``","``clang::argument_with_type_tag`` |br| ``clang::pointer_with_type_tag``","``clang::argument_with_type_tag`` |br| ``clang::pointer_with_type_tag``","","","",""
+
+Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx,
+type_tag_idx)))`` on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.
+
+This attribute is primarily useful for checking arguments of variadic functions
+(``pointer_with_type_tag`` can be used in most non-variadic cases).
+
+In the attribute prototype above:
+ * ``arg_kind`` is an identifier that should be used when annotating all
+ applicable type tags.
+ * ``arg_idx`` provides the position of a function argument. The expected type of
+ this function argument will be determined by the function argument specified
+ by ``type_tag_idx``. In the code example below, "3" means that the type of the
+ function's third argument will be determined by ``type_tag_idx``.
+ * ``type_tag_idx`` 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 ``arg_idx``. 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 ``arg_idx``.
+
+For example:
+
+.. code-block:: c++
+
+ int fcntl(int fd, int cmd, ...)
+ __attribute__(( argument_with_type_tag(fcntl,3,2) ));
+ // The function's second argument will be a type tag; this type tag will
+ // determine the expected type of the function's third argument.
+
+
+pointer_with_type_tag
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``argument_with_type_tag`` |br| ``pointer_with_type_tag``","``clang::argument_with_type_tag`` |br| ``clang::pointer_with_type_tag``","``clang::argument_with_type_tag`` |br| ``clang::pointer_with_type_tag``","","","",""
+
+Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))``
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.
+
+In the attribute prototype above:
+ * ``ptr_kind`` is an identifier that should be used when annotating all
+ applicable type tags.
+ * ``ptr_idx`` 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
+ ``type_tag_idx``. In the code example below, "1" means that the pointee type
+ of the function's first argument will be determined by ``type_tag_idx``.
+ * ``type_tag_idx`` 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 ``ptr_idx``. 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 ``ptr_idx``.
+
+For example:
+
+.. code-block:: c++
+
+ typedef int MPI_Datatype;
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+ // The function's 3rd argument will be a type tag; this type tag will
+ // determine the expected pointee type of the function's 1st argument.
+
+
+type_tag_for_datatype
+---------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``type_tag_for_datatype``","``clang::type_tag_for_datatype``","``clang::type_tag_for_datatype``","","","",""
+
+When declaring a variable, use
+``__attribute__((type_tag_for_datatype(kind, type)))`` to create a type tag that
+is tied to the ``type`` argument given to the attribute.
+
+In the attribute prototype above:
+ * ``kind`` is an identifier that should be used when annotating all applicable
+ type tags.
+ * ``type`` indicates the name of the type.
+
+Clang supports annotating type tags of two forms.
+
+ * **Type tag that is a reference to a declared identifier.**
+ Use ``__attribute__((type_tag_for_datatype(kind, type)))`` when declaring that
+ identifier:
+
+ .. code-block:: c++
+
+ typedef int MPI_Datatype;
+ extern struct mpi_datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) ));
+ #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
+ // &mpi_datatype_int is a type tag. It is tied to type "int".
+
+ * **Type tag that is an integral literal.**
+ Declare a ``static const`` variable with an initializer value and attach
+ ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration:
+
+ .. code-block:: c++
+
+ typedef int MPI_Datatype;
+ static const MPI_Datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) )) = 42;
+ #define MPI_INT ((MPI_Datatype) 42)
+ // The number 42 is a type tag. It is tied to type "int".
+
+
+The ``type_tag_for_datatype`` attribute also accepts an optional third argument
+that determines how the type of the function argument specified by either
+``arg_idx`` or ``ptr_idx`` is compared against the type associated with the type
+tag. (Recall that for the ``argument_with_type_tag`` attribute, the type of the
+function argument specified by ``arg_idx`` is compared against the type
+associated with the type tag. Also recall that for the ``pointer_with_type_tag``
+attribute, the pointee type of the function argument specified by ``ptr_idx`` is
+compared against the type associated with the type tag.) There are two supported
+values for this optional third argument:
+
+ * ``layout_compatible`` 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:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ typedef int MPI_Datatype;
+ struct internal_mpi_double_int { double d; int i; };
+ extern struct mpi_datatype mpi_datatype_double_int
+ __attribute__(( type_tag_for_datatype(mpi,
+ struct internal_mpi_double_int, layout_compatible) ));
+
+ #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning because the
+ // layout of my_pair is
+ // compatible with that of
+ // internal_mpi_double_int
+
+ struct my_int_pair { int a; int b; }
+ struct my_int_pair *buffer2;
+ MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning because the
+ // layout of my_int_pair
+ // does not match that of
+ // internal_mpi_double_int
+
+ * ``must_be_null`` specifies that the function argument specified by either
+ ``arg_idx`` (for the ``argument_with_type_tag`` attribute) or ``ptr_idx`` (for
+ the ``pointer_with_type_tag`` attribute) should be a null pointer constant.
+ The second argument to the ``type_tag_for_datatype`` attribute is ignored. For
+ example:
+
+ .. code-block:: c++
+
+ /* In mpi.h */
+ typedef int MPI_Datatype;
+ extern struct mpi_datatype mpi_datatype_null
+ __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
+
+ #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL
+ // was specified but buffer
+ // is not a null pointer
+
+
+Nullability Attributes
+======================
+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 ``nonnull`` and ``returns_nonnull`` 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 (``_Nullable``) or cannot be null (``_Nonnull``).
+
+The nullability (type) qualifiers express whether a value of a given pointer type can be null (the ``_Nullable`` qualifier), doesn't have a defined meaning for null (the ``_Nonnull`` qualifier), or for which the purpose of null is unclear (the ``_Null_unspecified`` qualifier). Because nullability qualifiers are expressed within the type system, they are more general than the ``nonnull`` and ``returns_nonnull`` 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:
+
+ .. code-block:: c
+
+ // No meaningful result when 'ptr' is null (here, it happens to be undefined behavior).
+ int fetch(int * _Nonnull ptr) { return *ptr; }
+
+ // 'ptr' may be null.
+ int fetch_or_zero(int * _Nullable ptr) {
+ return ptr ? *ptr : 0;
+ }
+
+ // A nullable pointer to non-null pointers to const characters.
+ const char *join_strings(const char * _Nonnull * _Nullable strings, unsigned n);
+
+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:
+
+ .. code-block:: objective-c
+
+ @interface NSView : NSResponder
+ - (nullable NSView *)ancestorSharedWithView:(nonnull NSView *)aView;
+ @property (assign, nullable) NSView *superview;
+ @property (readonly, nonnull) NSArray *subviews;
+ @end
+
+_Nonnull
+--------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``_Nonnull``","",""
+
+The ``_Nonnull`` nullability qualifier indicates that null is not a meaningful value for a value of the ``_Nonnull`` pointer type. For example, given a declaration such as:
+
+ .. code-block:: c
+
+ int fetch(int * _Nonnull ptr);
+
+a caller of ``fetch`` should not provide a null value, and the compiler will produce a warning if it sees a literal null value passed to ``fetch``. Note that, unlike the declaration attribute ``nonnull``, the presence of ``_Nonnull`` does not imply that passing null is undefined behavior: ``fetch`` is free to consider null undefined behavior or (perhaps for backward-compatibility reasons) defensively handle null.
+
+
+_Null_unspecified
+-----------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``_Null_unspecified``","",""
+
+The ``_Null_unspecified`` nullability qualifier indicates that neither the ``_Nonnull`` nor ``_Nullable`` 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.
+
+
+_Nullable
+---------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "","","","","``_Nullable``","",""
+
+The ``_Nullable`` nullability qualifier indicates that a value of the ``_Nullable`` pointer type can be null. For example, given:
+
+ .. code-block:: c
+
+ int fetch_or_zero(int * _Nullable ptr);
+
+a caller of ``fetch_or_zero`` can provide null.
+
+
+nonnull
+-------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``nonnull``","``gnu::nonnull``","","","","",""
+
+The ``nonnull`` attribute indicates that some function parameters must not be null, and can be used in several different ways. It's original usage (`from GCC <https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes>`_) 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:
+
+ .. code-block:: c
+
+ extern void * my_memcpy (void *dest, const void *src, size_t len)
+ __attribute__((nonnull (1, 2)));
+
+Here, the ``nonnull`` 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:
+
+ .. code-block:: c
+
+ extern void * my_memcpy (void *dest, const void *src, size_t len)
+ __attribute__((nonnull));
+
+Clang also allows the ``nonnull`` 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:
+
+ .. code-block:: c
+
+ extern void * my_memcpy (void *dest __attribute__((nonnull)),
+ const void *src __attribute__((nonnull)), size_t len);
+
+Note that the ``nonnull`` 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 ``_Nonnull`` 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.
+
+
+returns_nonnull
+---------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "C2x", "``__declspec``", "Keyword", "``#pragma``", "``#pragma clang attribute``"
+
+ "``returns_nonnull``","``gnu::returns_nonnull``","","","","","Yes"
+
+The ``returns_nonnull`` attribute indicates that a particular function (or Objective-C method) always returns a non-null pointer. For example, a particular system ``malloc`` might be defined to terminate a process when memory is not available rather than returning a null pointer:
+
+ .. code-block:: c
+
+ extern void * malloc (size_t size) __attribute__((returns_nonnull));
+
+The ``returns_nonnull`` attribute implies that returning a null pointer is undefined behavior, which the optimizer may take advantage of. The ``_Nonnull`` 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
+
+
Added: www-releases/trunk/9.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.rst.txt (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,2385 @@
+.. FIXME: move to the stylesheet or Sphinx plugin
+
+.. raw:: html
+
+ <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:
+ * https://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>
+
+.. role:: arc-term
+.. role:: revision
+.. role:: when-revised
+
+==============================================
+Objective-C Automatic Reference Counting (ARC)
+==============================================
+
+.. contents::
+ :local:
+
+.. _arc.meta:
+
+About this document
+===================
+
+.. _arc.meta.purpose:
+
+Purpose
+-------
+
+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.
+
+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.
+
+.. _arc.meta.background:
+
+Background
+----------
+
+This document assumes a basic familiarity with C.
+
+:arc-term:`Blocks` are a C language extension for creating anonymous functions.
+Users interact with and transfer block objects using :arc-term:`block
+pointers`, 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 ``Block_copy`` 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
+``Block_release``, which decreases the reference count by 1 and destroys the
+object if the count reaches zero and is on the heap.
+
+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.
+
+Objective-C defines a new type kind, collectively called the :arc-term:`object
+pointer types`. This kind has two notable builtin members, ``id`` and
+``Class``; ``id`` is the final supertype of all object pointers. The validity
+of conversions between object pointer types is not checked at runtime. Users
+may define :arc-term:`classes`; 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
+:arc-term:`ivars`, fields which appear on all instances of that class. For
+every class *T* there's an associated metaclass; it has no fields, its
+superclass is the metaclass of *T*'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
+``Class``.
+
+A class declaration (``@interface``) declares a set of :arc-term:`methods`. A
+method has a return type, a list of argument types, and a :arc-term:`selector`:
+a name like ``foo:bar:baz:``, 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 :arc-term:`receiver`) and a list of formal
+arguments interspersed with the selector, like so:
+
+.. code-block:: objc
+
+ [receiver foo: fooArg bar: barArg baz: bazArg]
+
+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 ``super``, 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 ``@interface``, but
+those defined in a separate ``@implementation`` declaration; however, when
+compiling a call, typechecking is done based on the methods declared in the
+``@interface``.
+
+Method declarations may also be grouped into :arc-term:`protocols`, 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.
+
+:arc-term:`Class extensions` are collections of ivars and methods, designed to
+allow a class's ``@interface`` to be split across multiple files; however,
+there is still a primary implementation file which must see the
+``@interface``\ s of all class extensions. :arc-term:`Categories` allow
+methods (but not ivars) to be declared *post hoc* on an arbitrary class; the
+methods in the category's ``@implementation`` 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.
+
+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: ``retain``
+increases the object's reference count by 1, whereas ``release`` decreases it
+by 1 and calls the instance method ``dealloc`` if the count reaches 0. To
+simplify certain operations, there is also an :arc-term:`autorelease pool`, a
+thread-local list of objects to call ``release`` on later; an object can be
+added to this pool by calling ``autorelease`` on it.
+
+Block pointers may be converted to type ``id``; 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 ``retain`` by adjusting the reference count, not by calling
+``Block_copy``.
+
+.. _arc.meta.evolution:
+
+Evolution
+---------
+
+ARC is under continual evolution, and this document must be updated as the
+language progresses.
+
+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:
+
+ ARC applies to Objective-C pointer types, block pointer types, and
+ :when-revised:`[beginning Apple 8.0, LLVM 3.8]` :revision:`BPTRs declared
+ within` ``extern "BCPL"`` blocks.
+
+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.
+
+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.
+
+.. _arc.general:
+
+General
+=======
+
+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.
+
+ARC may be explicitly enabled with the compiler flag ``-fobjc-arc``. It may
+also be explicitly disabled with the compiler flag ``-fno-objc-arc``. The last
+of these two flags appearing on the compile line "wins".
+
+If ARC is enabled, ``__has_feature(objc_arc)`` will expand to 1 in the
+preprocessor. For more information about ``__has_feature``, see the
+:ref:`language extensions <langext-__has_feature-__has_extension>` document.
+
+.. _arc.objects:
+
+Retainable object pointers
+==========================
+
+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 *values* (patterns of bits indicating the location
+of a pointed-to object), not pointer *objects* (locations in memory which store
+pointer values). The rules for objects are covered in the next section.
+
+A :arc-term:`retainable object pointer` (or "retainable pointer") is a value of
+a :arc-term:`retainable object pointer type` ("retainable type"). There are
+three kinds of retainable object pointer types:
+
+* block pointers (formed by applying the caret (``^``) declarator sigil to a
+ function type)
+* Objective-C object pointers (``id``, ``Class``, ``NSFoo*``, etc.)
+* typedefs marked with ``__attribute__((NSObject))``
+
+Other pointer types, such as ``int*`` and ``CFStringRef``, are not subject to
+ARC's semantics and restrictions.
+
+.. admonition:: Rationale
+
+ 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:
+
+ * The type system must reliably identify which objects are to be managed. An
+ ``int*`` might be a pointer to a ``malloc``'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.
+
+ * 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.
+
+ * 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 macOS, 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.
+
+The use of ``__attribute__((NSObject))`` 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
+``__typeof`` and C++ template argument substitution.
+
+.. admonition:: Rationale
+
+ Any compiler operation which incidentally strips type "sugar" from a type
+ will yield a type without the attribute, which may result in unexpected
+ behavior.
+
+.. _arc.objects.retains:
+
+Retain count semantics
+----------------------
+
+A retainable object pointer is either a :arc-term:`null pointer` or a pointer
+to a valid object. Furthermore, if it has block pointer type and is not
+``null`` then it must actually be a pointer to a block object, and if it has
+``Class`` 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.
+
+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:
+
+* ``retain``, taking no arguments and returning a pointer to the object.
+* ``release``, taking no arguments and returning ``void``.
+* ``autorelease``, taking no arguments and returning a pointer to the object.
+
+The behavior of these methods is constrained in the following ways. The term
+:arc-term:`high-level semantics` 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 ``retain``, 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.
+
+It is undefined behavior if a computation history featuring a send of
+``retain`` followed by a send of ``release`` to the same object, with no
+intervening ``release`` 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.
+
+It is undefined behavior if a computation history features any use whatsoever
+of an object following the completion of a send of ``release`` that is not
+preceded by a send of ``retain`` to the same object.
+
+The behavior of ``autorelease`` must be equivalent to sending ``release`` when
+one of the autorelease pools currently in scope is popped. It may not throw an
+exception.
+
+When the semantics call for performing one of these operations on a retainable
+object pointer, if that pointer is ``null`` then the effect is a no-op.
+
+All of the semantics described in this document are subject to additional
+:ref:`optimization rules <arc.optimization>` 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.
+
+.. _arc.objects.operands:
+
+Retainable object pointers as operands and arguments
+----------------------------------------------------
+
+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:
+
+* loading a retainable pointer from an object with non-weak :ref:`ownership
+ <arc.ownership>`,
+* passing a retainable pointer as an argument to a function or method, and
+* receiving a retainable pointer as the result of a function or method call.
+
+.. admonition:: Rationale
+
+ 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.
+
+The remainder of this section describes exceptions to these rules, how those
+exceptions are detected, and what those exceptions imply semantically.
+
+.. _arc.objects.operands.consumed:
+
+Consumed parameters
+^^^^^^^^^^^^^^^^^^^
+
+A function or method parameter of retainable object pointer type may be marked
+as :arc-term:`consumed`, signifying that the callee expects to take ownership
+of a +1 retain count. This is done by adding the ``ns_consumed`` attribute to
+the parameter declaration, like so:
+
+.. code-block:: objc
+
+ void foo(__attribute((ns_consumed)) id x);
+ - (void) foo: (id) __attribute((ns_consumed)) x;
+
+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.
+
+When passing such an argument, ARC retains the argument prior to making the
+call.
+
+When receiving such an argument, ARC releases the argument at the end of the
+function, subject to the usual optimizations for local values.
+
+.. admonition:: Rationale
+
+ This formalizes direct transfers of ownership from a caller to a callee. The
+ most common scenario here is passing the ``self`` parameter to ``init``, 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.
+
+The implicit ``self`` parameter of a method may be marked as consumed by adding
+``__attribute__((ns_consumes_self))`` to the method declaration. Methods in
+the ``init`` :ref:`family <arc.method-families>` are treated as if they were
+implicitly marked with this attribute.
+
+It is undefined behavior if an Objective-C message send to a method with
+``ns_consumed`` 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 ``ns_consumed`` 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
+``ns_consumed`` parameters than the implementation of the called block or
+function.
+
+.. admonition:: Rationale
+
+ 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.
+
+.. _arc.object.operands.retained-return-values:
+
+Retained return values
+^^^^^^^^^^^^^^^^^^^^^^
+
+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
+``ns_returns_retained`` attribute to the function or method declaration, like
+so:
+
+.. code-block:: objc
+
+ id foo(void) __attribute((ns_returns_retained));
+ - (id) foo __attribute((ns_returns_retained));
+
+This attribute is part of the type of the function or method.
+
+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.
+
+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.
+
+.. admonition:: Rationale
+
+ This formalizes direct transfers of ownership from a callee to a caller. The
+ most common scenario this models is the retained return from ``init``,
+ ``alloc``, ``new``, and ``copy`` methods, but there are other cases in the
+ frameworks. After optimization there are typically no extra retains and
+ releases required.
+
+Methods in the ``alloc``, ``copy``, ``init``, ``mutableCopy``, and ``new``
+:ref:`families <arc.method-families>` are implicitly marked
+``__attribute__((ns_returns_retained))``. This may be suppressed by explicitly
+marking the method ``__attribute__((ns_returns_not_retained))``.
+
+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.
+
+.. admonition:: Rationale
+
+ 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.
+
+.. _arc.objects.operands.unretained-returns:
+
+Unretained return values
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+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 ``autorelease``, but
+callers must not assume that the value is actually in the autorelease pool.
+
+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.
+
+.. admonition:: Rationale
+
+ 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.
+
+A method or function may be marked with
+``__attribute__((ns_returns_autoreleased))`` 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.
+
+.. _arc.objects.operands.casts:
+
+Bridged casts
+^^^^^^^^^^^^^
+
+A :arc-term:`bridged cast` is a C-style cast annotated with one of three
+keywords:
+
+* ``(__bridge T) op`` casts the operand to the destination type ``T``. If
+ ``T`` is a retainable object pointer type, then ``op`` must have a
+ non-retainable pointer type. If ``T`` is a non-retainable pointer type,
+ then ``op`` 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.
+* ``(__bridge_retained T) op`` 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.
+* ``(__bridge_transfer T) op`` 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.
+
+These casts are required in order to transfer objects in and out of ARC
+control; see the rationale in the section on :ref:`conversion of retainable
+object pointers <arc.objects.restrictions.conversion>`.
+
+Using a ``__bridge_retained`` or ``__bridge_transfer`` cast purely to convince
+ARC to emit an unbalanced retain or release, respectively, is poor form.
+
+.. _arc.objects.restrictions:
+
+Restrictions
+------------
+
+.. _arc.objects.restrictions.conversion:
+
+Conversion of retainable object pointers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 ``void*``. As an exception, cast to ``intptr_t`` is
+allowed because such casts are not transferring ownership. The :ref:`bridged
+casts <arc.objects.operands.casts>` may be used to perform these conversions
+where necessary.
+
+.. admonition:: Rationale
+
+ 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.
+
+However, the following exceptions apply.
+
+.. _arc.objects.restrictions.conversion.with.known.semantics:
+
+Conversion to retainable object pointer type of expressions with known semantics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+: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.`
+
+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.
+
+An expression is :arc-term:`known retain-agnostic` if it is:
+
+* an Objective-C string literal,
+* a load from a ``const`` system global variable of :ref:`C retainable pointer
+ type <arc.misc.c-retainable>`, or
+* a null pointer constant.
+
+An expression is :arc-term:`known unretained` if it is an rvalue of :ref:`C
+retainable pointer type <arc.misc.c-retainable>` and it is:
+
+* a direct call to a function, and either that function has the
+ ``cf_returns_not_retained`` attribute or it is an :ref:`audited
+ <arc.misc.c-retainable.audit>` function that does not have the
+ ``cf_returns_retained`` attribute and does not follow the create/copy naming
+ convention,
+* a message send, and the declared method either has the
+ ``cf_returns_not_retained`` attribute or it has neither the
+ ``cf_returns_retained`` attribute nor a :ref:`selector family
+ <arc.method-families>` that implies a retained result, or
+* :when-revised:`[beginning LLVM 3.6]` :revision:`a load from a` ``const``
+ :revision:`non-system global variable.`
+
+An expression is :arc-term:`known retained` if it is an rvalue of :ref:`C
+retainable pointer type <arc.misc.c-retainable>` and it is:
+
+* a message send, and the declared method either has the
+ ``cf_returns_retained`` attribute, or it does not have the
+ ``cf_returns_not_retained`` attribute but it does have a :ref:`selector
+ family <arc.method-families>` that implies a retained result.
+
+Furthermore:
+
+* a comma expression is classified according to its right-hand side,
+* a statement expression is classified according to its result expression, if
+ it has one,
+* an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is
+ classified according to the underlying message send, and
+* 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.
+
+If the cast operand is known retained, the conversion is treated as a
+``__bridge_transfer`` cast. If the cast operand is known unretained or known
+retain-agnostic, the conversion is treated as a ``__bridge`` cast.
+
+.. admonition:: Rationale
+
+ 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.
+
+ We've so far consciously refrained from implicitly turning retained CF
+ results from function calls into ``__bridge_transfer`` casts. The worry is
+ that some code patterns --- for example, creating a CF value, assigning it
+ to an ObjC-typed local, and then calling ``CFRelease`` when done --- are a
+ bit too likely to be accidentally accepted, leading to mysterious behavior.
+
+ For loads from ``const`` global variables of :ref:`C retainable pointer type
+ <arc.misc.c-retainable>`, 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.
+
+.. _arc.objects.restrictions.conversion-exception-contextual:
+
+Conversion from retainable object pointer type in certain contexts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+
+If an expression of retainable object pointer type is explicitly cast to a
+:ref:`C retainable pointer type <arc.misc.c-retainable>`, the program is
+ill-formed as discussed above unless the result is immediately used:
+
+* to initialize a parameter in an Objective-C message send where the parameter
+ is not marked with the ``cf_consumed`` attribute, or
+* to initialize a parameter in a direct call to an
+ :ref:`audited <arc.misc.c-retainable.audit>` function where the parameter is
+ not marked with the ``cf_consumed`` attribute.
+
+.. admonition:: Rationale
+
+ 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 ``Release`` family,
+ and it would be quite unfortunate for explicit releases to be silently
+ balanced out in this way.
+
+.. _arc.ownership:
+
+Ownership qualification
+=======================
+
+This section describes the behavior of *objects* of retainable object pointer
+type; that is, locations in memory which store retainable object pointers.
+
+A type is a :arc-term:`retainable object owner type` if it is a retainable
+object pointer type or an array type whose element type is a retainable object
+owner type.
+
+An :arc-term:`ownership qualifier` 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.
+
+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.
+
+When forming a function type, the result type is adjusted so that any
+top-level ownership qualifier is deleted.
+
+Except as described under the :ref:`inference rules <arc.ownership.inference>`,
+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.
+
+.. admonition:: Rationale
+
+ 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 :ref:`inference of __strong for template type
+ arguments <arc.ownership.inference.template.arguments>`. Ownership qualifiers
+ on return types are dropped because they serve no purpose there except to
+ cause spurious problems with overloading and templates.
+
+There are four ownership qualifiers:
+
+* ``__autoreleasing``
+* ``__strong``
+* ``__unsafe_unretained``
+* ``__weak``
+
+A type is :arc-term:`nontrivially ownership-qualified` if it is qualified with
+``__autoreleasing``, ``__strong``, or ``__weak``.
+
+.. _arc.ownership.spelling:
+
+Spelling
+--------
+
+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.
+
+An ownership qualifier may be written anywhere that any other type qualifier
+may be written.
+
+If an ownership qualifier appears in the *declaration-specifiers*, the
+following rules apply:
+
+* if the type specifier is a retainable object owner type, the qualifier
+ initially applies to that type;
+
+* otherwise, if the outermost non-array declarator is a pointer
+ or block pointer declarator, the qualifier initially applies to
+ that type;
+
+* otherwise the program is ill-formed.
+
+* 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.
+
+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.
+
+If an ownership qualifier appears anywhere else in a declarator, it applies to
+the type there.
+
+.. admonition:: Rationale
+
+ Ownership qualifiers are like ``const`` and ``volatile`` 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, ``__strong``
+ before the entire declaration and have it apply in the leftmost
+ sensible place.
+
+.. _arc.ownership.spelling.property:
+
+Property declarations
+^^^^^^^^^^^^^^^^^^^^^
+
+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
+``__autoreleasing`` ownership.
+
+* ``assign`` implies ``__unsafe_unretained`` ownership.
+* ``copy`` implies ``__strong`` ownership, as well as the usual behavior of
+ copy semantics on the setter.
+* ``retain`` implies ``__strong`` ownership.
+* ``strong`` implies ``__strong`` ownership.
+* ``unsafe_unretained`` implies ``__unsafe_unretained`` ownership.
+* ``weak`` implies ``__weak`` ownership.
+
+With the exception of ``weak``, these modifiers are available in non-ARC
+modes.
+
+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 :arc-term:`associated instance variable` is
+the instance variable which is named, possibly implicitly, by the
+``@synthesize`` 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.
+
+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, :when-revised:`[beginning Apple 3.1, LLVM 3.1]`
+:revision:`its ownership is implicitly` ``strong``. Prior to this revision, it
+was ill-formed to synthesize such a property.
+
+.. admonition:: Rationale
+
+ Using ``strong`` by default is safe and consistent with the generic ARC rule
+ about :ref:`inferring ownership <arc.ownership.inference.variables>`. It is,
+ unfortunately, inconsistent with the non-ARC rule which states that such
+ properties are implicitly ``assign``. 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.
+
+Applying ``__attribute__((NSObject))`` 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 ``assign``. 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.
+
+.. _arc.ownership.semantics:
+
+Semantics
+---------
+
+There are five :arc-term:`managed operations` 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.
+
+A load or store with "primitive semantics" has the same semantics as the
+respective operation would have on an ``void*`` lvalue with the same alignment
+and non-ownership qualification.
+
+:arc-term:`Reading` occurs when performing a lvalue-to-rvalue conversion on an
+object lvalue.
+
+* For ``__weak`` 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.
+* For all other objects, the lvalue is loaded with primitive semantics.
+
+:arc-term:`Assignment` occurs when evaluating an assignment operator. The
+semantics vary based on the qualification:
+
+* For ``__strong`` 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.
+* For ``__weak`` 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.
+* For ``__unsafe_unretained`` objects, the new pointee is stored into the
+ lvalue using primitive semantics.
+* For ``__autoreleasing`` objects, the new pointee is retained, autoreleased,
+ and stored into the lvalue using primitive semantics.
+
+:arc-term:`Initialization` occurs when an object's lifetime begins, which
+depends on its storage duration. Initialization proceeds in two stages:
+
+#. First, a null pointer is stored into the lvalue using primitive semantics.
+ This step is skipped if the object is ``__unsafe_unretained``.
+#. Second, if the object has an initializer, that expression is evaluated and
+ then assigned into the object using the usual assignment semantics.
+
+:arc-term:`Destruction` 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.
+
+:arc-term:`Moving` 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 ``__block`` variables
+and rvalue references in C++. For ``__strong`` 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.
+
+.. _arc.ownership.restrictions:
+
+Restrictions
+------------
+
+.. _arc.ownership.restrictions.weak:
+
+Weak-unavailable types
+^^^^^^^^^^^^^^^^^^^^^^
+
+It is explicitly permitted for Objective-C classes to not support ``__weak``
+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 ``__weak`` references.
+
+.. admonition:: Rationale
+
+ Historically, it has been possible for a class to provide its own
+ reference-count implementation by overriding ``retain``, ``release``, 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.
+
+A class may indicate that it does not support weak references by providing the
+``objc_arc_weak_reference_unavailable`` attribute on the class's interface declaration. A
+retainable object pointer type is **weak-unavailable** if
+is a pointer to an (optionally protocol-qualified) Objective-C class ``T`` where
+``T`` or one of its superclasses has the ``objc_arc_weak_reference_unavailable``
+attribute. A program is ill-formed if it applies the ``__weak`` ownership
+qualifier to a weak-unavailable type or if the value operand of a weak
+assignment operation has a weak-unavailable type.
+
+.. _arc.ownership.restrictions.autoreleasing:
+
+Storage duration of ``__autoreleasing`` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it declares an ``__autoreleasing`` object of
+non-automatic storage duration. A program is ill-formed if it captures an
+``__autoreleasing`` object in a block or, unless by reference, in a C++11
+lambda.
+
+.. admonition:: Rationale
+
+ 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.
+
+It is undefined behavior if a non-null pointer is assigned to an
+``__autoreleasing`` object while an autorelease pool is in scope and then that
+object is read after the autorelease pool's scope is left.
+
+.. _arc.ownership.restrictions.conversion.indirect:
+
+Conversion of pointers to ownership-qualified types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if an expression of type ``T*`` is converted,
+explicitly or implicitly, to the type ``U*``, where ``T`` and ``U`` have
+different ownership qualification, unless:
+
+* ``T`` is qualified with ``__strong``, ``__autoreleasing``, or
+ ``__unsafe_unretained``, and ``U`` is qualified with both ``const`` and
+ ``__unsafe_unretained``; or
+* either ``T`` or ``U`` is ``cv void``, where ``cv`` is an optional sequence
+ of non-ownership qualifiers; or
+* the conversion is requested with a ``reinterpret_cast`` in Objective-C++; or
+* the conversion is a well-formed :ref:`pass-by-writeback
+ <arc.ownership.restrictions.pass_by_writeback>`.
+
+The analogous rule applies to ``T&`` and ``U&`` in Objective-C++.
+
+.. admonition:: Rationale
+
+ These rules provide a reasonable level of type-safety for indirect pointers,
+ as long as the underlying memory is not deallocated. The conversion to
+ ``const __unsafe_unretained`` 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 ``void*`` is useful for allocating
+ memory or otherwise escaping the type system, but use it carefully.
+ ``reinterpret_cast`` is considered to be an obvious enough sign of taking
+ responsibility for any problems.
+
+It is undefined behavior to access an ownership-qualified object through an
+lvalue of a differently-qualified type, except that any non-``__weak`` object
+may be read through an ``__unsafe_unretained`` lvalue.
+
+It is undefined behavior if the storage of a ``__strong`` or ``__weak``
+object is not properly initialized before the first managed operation
+is performed on the object, or if the storage of such an object is freed
+or reused before the object has been properly deinitialized. Storage for
+a ``__strong`` or ``__weak`` object may be properly initialized by filling
+it with the representation of a null pointer, e.g. by acquiring the memory
+with ``calloc`` or using ``bzero`` to zero it out. A ``__strong`` or
+``__weak`` object may be properly deinitialized by assigning a null pointer
+into it. A ``__strong`` object may also be properly initialized
+by copying into it (e.g. with ``memcpy``) the representation of a
+different ``__strong`` object whose storage has been properly initialized;
+doing this properly deinitializes the source object and causes its storage
+to no longer be properly initialized. A ``__weak`` object may not be
+representation-copied in this way.
+
+These requirements are followed automatically for objects whose
+initialization and deinitialization are under the control of ARC:
+
+* objects of static, automatic, and temporary storage duration
+* instance variables of Objective-C objects
+* elements of arrays where the array object's initialization and
+ deinitialization are under the control of ARC
+* fields of Objective-C struct types where the struct object's
+ initialization and deinitialization are under the control of ARC
+* non-static data members of Objective-C++ non-union class types
+* Objective-C++ objects and arrays of dynamic storage duration created
+ with the ``new`` or ``new[]`` operators and destroyed with the
+ corresponding ``delete`` or ``delete[]`` operator
+
+They are not followed automatically for these objects:
+
+* objects of dynamic storage duration created in other memory, such as
+ that returned by ``malloc``
+* union members
+
+.. admonition:: Rationale
+
+ ARC must perform special operations when initializing an object and
+ when destroying it. In many common situations, ARC knows when an
+ object is created and when it is destroyed and can ensure that these
+ operations are performed correctly. Otherwise, however, ARC requires
+ programmer cooperation to establish its initialization invariants
+ because it is infeasible for ARC to dynamically infer whether they
+ are intact. For example, there is no syntactic difference in C between
+ an assignment that is intended by the programmer to initialize a variable
+ and one that is intended to replace the existing value stored there,
+ but ARC must perform one operation or the other. ARC chooses to always
+ assume that objects are initialized (except when it is in charge of
+ initializing them) because the only workable alternative would be to
+ ban all code patterns that could potentially be used to access
+ uninitialized memory, and that would be too limiting. In practice,
+ this is rarely a problem because programmers do not generally need to
+ work with objects for which the requirements are not handled
+ automatically.
+
+Note that dynamically-allocated Objective-C++ arrays of
+nontrivially-ownership-qualified type are not ABI-compatible with non-ARC
+code because the non-ARC code will consider the element type to be POD.
+Such arrays that are ``new[]``'d in ARC translation units cannot be
+``delete[]``'d in non-ARC translation units and vice-versa.
+
+.. _arc.ownership.restrictions.pass_by_writeback:
+
+Passing to an out parameter by writeback
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the argument passed to a parameter of type ``T __autoreleasing *`` has type
+``U oq *``, where ``oq`` is an ownership qualifier, then the argument is a
+candidate for :arc-term:`pass-by-writeback`` if:
+
+* ``oq`` is ``__strong`` or ``__weak``, and
+* it would be legal to initialize a ``T __strong *`` with a ``U __strong *``.
+
+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.
+
+The pass-by-writeback is ill-formed if the argument expression does not have a
+legal form:
+
+* ``&var``, where ``var`` is a scalar variable of automatic storage duration
+ with retainable object pointer type
+* a conditional expression where the second and third operands are both legal
+ forms
+* a cast whose operand is a legal form
+* a null pointer constant
+
+.. admonition:: Rationale
+
+ 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.
+
+A pass-by-writeback is evaluated as follows:
+
+#. The argument is evaluated to yield a pointer ``p`` of type ``U oq *``.
+#. If ``p`` is a null pointer, then a null pointer is passed as the argument,
+ and no further work is required for the pass-by-writeback.
+#. Otherwise, a temporary of type ``T __autoreleasing`` is created and
+ initialized to a null pointer.
+#. If the parameter is not an Objective-C method parameter marked ``out``,
+ then ``*p`` is read, and the result is written into the temporary with
+ primitive semantics.
+#. The address of the temporary is passed as the argument to the actual call.
+#. After the call completes, the temporary is loaded with primitive
+ semantics, and that value is assigned into ``*p``.
+
+.. admonition:: Rationale
+
+ 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 ``__autoreleasing`` rather than ``__strong``. 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
+ ``__autoreleasing`` on all the variables they intend to use for
+ out-parameters. This was the least bad solution.
+
+.. _arc.ownership.restrictions.records:
+
+Ownership-qualified fields of structs and unions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it declares a member of a C struct or union to have
+a nontrivially ownership-qualified type.
+
+.. admonition:: Rationale
+
+ 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 ``void*`` or an ``__unsafe_unretained`` object.
+
+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.
+
+.. admonition:: Rationale
+
+ 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.
+
+.. _arc.ownership.inference:
+
+Ownership inference
+-------------------
+
+.. _arc.ownership.inference.variables:
+
+Objects
+^^^^^^^
+
+If an object is declared with retainable object owner type, but without an
+explicit ownership qualifier, its type is implicitly adjusted to have
+``__strong`` qualification.
+
+As a special case, if the object's base type is ``Class`` (possibly
+protocol-qualified), the type is adjusted to have ``__unsafe_unretained``
+qualification instead.
+
+.. _arc.ownership.inference.indirect_parameters:
+
+Indirect parameters
+^^^^^^^^^^^^^^^^^^^
+
+If a function or method parameter has type ``T*``, where ``T`` is an
+ownership-unqualified retainable object pointer type, then:
+
+* if ``T`` is ``const``-qualified or ``Class``, then it is implicitly
+ qualified with ``__unsafe_unretained``;
+* otherwise, it is implicitly qualified with ``__autoreleasing``.
+
+.. admonition:: Rationale
+
+ ``__autoreleasing`` exists mostly for this case, the Cocoa convention for
+ out-parameters. Since a pointer to ``const`` 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 *mutable* array, inferring
+ ``__autoreleasing`` is the wrong thing to do; this directs some of the
+ caution in the following rules about writeback.
+
+Such a type written anywhere else would be ill-formed by the general rule
+requiring ownership qualifiers.
+
+This rule does not apply in Objective-C++ if a parameter's type is dependent in
+a template pattern and is only *instantiated* to a type which would be a
+pointer to an unqualified retainable object pointer type. Such code is still
+ill-formed.
+
+.. admonition:: Rationale
+
+ The convention is very unlikely to be intentional in template code.
+
+.. _arc.ownership.inference.template.arguments:
+
+Template arguments
+^^^^^^^^^^^^^^^^^^
+
+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 ``__strong`` qualification. This adjustment occurs regardless of
+whether the template argument was deduced or explicitly specified.
+
+.. admonition:: Rationale
+
+ ``__strong`` is a useful default for containers (e.g., ``std::vector<id>``),
+ 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.
+
+.. _arc.method-families:
+
+Method families
+===============
+
+An Objective-C method may fall into a :arc-term:`method family`, which is a
+conventional set of behaviors ascribed to it by the Cocoa conventions.
+
+A method is in a certain method family if:
+
+* it has a ``objc_method_family`` attribute placing it in that family; or if
+ not that,
+* it does not have an ``objc_method_family`` attribute placing it in a
+ different or no family, and
+* its selector falls into the corresponding selector family, and
+* its signature obeys the added restrictions of the method family.
+
+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, ``_perform:with:`` and
+``performWith:`` would fall into the ``perform`` family (if we recognized one),
+but ``performing:with`` would not.
+
+The families and their added restrictions are:
+
+* ``alloc`` methods must return a retainable object pointer type.
+* ``copy`` methods must return a retainable object pointer type.
+* ``mutableCopy`` methods must return a retainable object pointer type.
+* ``new`` methods must return a retainable object pointer type.
+* ``init`` 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 ``init`` method whose return type is neither ``id`` 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).
+
+ .. admonition:: Rationale
+
+ There are a fair number of existing methods with ``init``-like selectors
+ which nonetheless don't follow the ``init`` conventions. Typically these
+ are either accidental naming collisions or helper methods called during
+ initialization. Because of the peculiar retain/release behavior of
+ ``init`` methods, it's very important not to treat these methods as
+ ``init`` 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 ``init`` family.
+
+ Note that a method with an ``init``-family selector which returns a
+ non-Objective-C type (e.g. ``void``) is perfectly well-formed; it simply
+ isn't in the ``init`` family.
+
+A program is ill-formed if a method's declarations, implementations, and
+overrides do not all have the same method family.
+
+.. _arc.family.attribute:
+
+Explicit method family control
+------------------------------
+
+A method may be annotated with the ``objc_method_family`` attribute to
+precisely control which method family it belongs to. If a method in an
+``@implementation`` does not have this attribute, but there is a method
+declared in the corresponding ``@interface`` that does, then the attribute is
+copied to the declaration in the ``@implementation``. The attribute is
+available outside of ARC, and may be tested for with the preprocessor query
+``__has_attribute(objc_method_family)``.
+
+The attribute is spelled
+``__attribute__((objc_method_family(`` *family* ``)))``. If *family* is
+``none``, the method has no family, even if it would otherwise be considered to
+have one based on its selector and type. Otherwise, *family* must be one of
+``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``, 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.
+
+.. admonition:: Rationale
+
+ 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
+ ``ns_returns_retained``, this attribute allows the user to communicate
+ semantic intent, which is of use both to ARC (which, e.g., treats calls to
+ ``init`` specially) and the static analyzer.
+
+.. _arc.family.semantics:
+
+Semantics of method families
+----------------------------
+
+A method's membership in a method family may imply non-standard semantics for
+its parameters and return type.
+
+Methods in the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families ---
+that is, methods in all the currently-defined families except ``init`` ---
+implicitly :ref:`return a retained object
+<arc.object.operands.retained-return-values>` as if they were annotated with
+the ``ns_returns_retained`` attribute. This can be overridden by annotating
+the method with either of the ``ns_returns_autoreleased`` or
+``ns_returns_not_retained`` attributes.
+
+Properties also follow same naming rules as methods. This means that those in
+the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families provide access
+to :ref:`retained objects <arc.object.operands.retained-return-values>`. This
+can be overridden by annotating the property with ``ns_returns_not_retained``
+attribute.
+
+.. _arc.family.semantics.init:
+
+Semantics of ``init``
+^^^^^^^^^^^^^^^^^^^^^
+
+Methods in the ``init`` family implicitly :ref:`consume
+<arc.objects.operands.consumed>` their ``self`` parameter and :ref:`return a
+retained object <arc.object.operands.retained-return-values>`. Neither of
+these properties can be altered through attributes.
+
+A call to an ``init`` method with a receiver that is either ``self`` (possibly
+parenthesized or casted) or ``super`` is called a :arc-term:`delegate init
+call`. It is an error for a delegate init call to be made except from an
+``init`` method, and excluding blocks within such methods.
+
+As an exception to the :ref:`usual rule <arc.misc.self>`, the variable ``self``
+is mutable in an ``init`` method and has the usual semantics for a ``__strong``
+variable. However, it is undefined behavior and the program is ill-formed, no
+diagnostic required, if an ``init`` method attempts to use the previous value
+of ``self`` after the completion of a delegate init call. It is conventional,
+but not required, for an ``init`` method to return ``self``.
+
+It is undefined behavior for a program to cause two or more calls to ``init``
+methods on the same object, except that each ``init`` method invocation may
+perform at most one delegate init call.
+
+.. _arc.family.semantics.result_type:
+
+Related result types
+^^^^^^^^^^^^^^^^^^^^
+
+Certain methods are candidates to have :arc-term:`related result types`:
+
+* class methods in the ``alloc`` and ``new`` method families
+* instance methods in the ``init`` family
+* the instance method ``self``
+* outside of ARC, the instance methods ``retain`` and ``autorelease``
+
+If the formal result type of such a method is ``id`` or protocol-qualified
+``id``, 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:
+
+* if it is a class method, and the receiver is a class name ``T``, the message
+ send expression has type ``T*``; otherwise
+* if it is an instance method, and the receiver has type ``T``, the message
+ send expression has type ``T``; otherwise
+* the message send expression has the normal result type of the method.
+
+This is a new rule of the Objective-C language and applies outside of ARC.
+
+.. admonition:: Rationale
+
+ 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.
+
+.. _arc.optimization:
+
+Optimization
+============
+
+Within this section, the word :arc-term:`function` will be used to
+refer to any structured unit of code, be it a C function, an
+Objective-C method, or a block.
+
+This specification describes ARC as performing specific ``retain`` and
+``release`` 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 :arc-term:`formal local retain history` of the
+object pointer. The corresponding actual sequence executed is the
+`dynamic local retain history`.
+
+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 :ref:`restrictions <arc.objects.retains>` on
+the implementation of ``retain`` and ``release``.
+
+.. admonition:: Rationale
+
+ Specifically, ARC is sometimes permitted to optimize ``release``
+ 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 ``retain``/``release`` pairs. For
+ example, consider the following code:
+
+ .. code-block:: objc
+
+ id x = _ivar;
+ [x foo];
+
+ If we were not permitted in any event to shorten the lifetime of the
+ object in ``x``, then we would not be able to eliminate this retain
+ and release unless we could prove that the message send could not
+ modify ``_ivar`` (or deallocate ``self``). Since message sends are
+ opaque to the optimizer, this is not possible, and so ARC's hands
+ would be almost completely tied.
+
+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.
+
+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).
+
+.. admonition:: Rationale
+
+ 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.
+
+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 ``__strong`` 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.
+
+.. _arc.optimization.liveness:
+
+Object liveness
+---------------
+
+ARC may not allow a retainable object ``X`` to be deallocated at a
+time ``T`` in a computation history if:
+
+* ``X`` is the value stored in a ``__strong`` object ``S`` with
+ :ref:`precise lifetime semantics <arc.optimization.precise>`, or
+
+* ``X`` is the value stored in a ``__strong`` object ``S`` with
+ imprecise lifetime semantics and, at some point after ``T`` but
+ before the next store to ``S``, the computation history features a
+ load from ``S`` and in some way depends on the value loaded, or
+
+* ``X`` is a value described as being released at the end of the
+ current full-expression and, at some point after ``T`` but before
+ the end of the full-expression, the computation history depends
+ on that value.
+
+.. admonition:: Rationale
+
+ The intent of the second rule is to say that objects held in normal
+ ``__strong`` 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.
+
+ The intent of the third rule is to say that return values may be
+ released after they've been used.
+
+A computation history depends on a pointer value ``P`` if it:
+
+* performs a pointer comparison with ``P``,
+* loads from ``P``,
+* stores to ``P``,
+* depends on a pointer value ``Q`` derived via pointer arithmetic
+ from ``P`` (including an instance-variable or field access), or
+* depends on a pointer value ``Q`` loaded from ``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 ``P``. Furthermore, this
+dependency is not carried by values that are stored to objects.
+
+.. admonition:: Rationale
+
+ 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.
+
+ Dependency propagates to values loaded from a pointer because those
+ values might be invalidated by deallocating the object. For
+ example, given the code ``__strong id x = p->ivar;``, ARC must not
+ move the release of ``p`` to between the load of ``p->ivar`` and the
+ retain of that value for storing into ``x``.
+
+ 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.
+
+ 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.
+
+.. _arc.optimization.object_lifetime:
+
+No object lifetime extension
+----------------------------
+
+If, in the formal computation history of the program, an object ``X``
+has been deallocated by the time of an observable side-effect, then
+ARC must cause ``X`` 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.
+
+.. admonition:: Rationale
+
+ 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.
+
+ 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.
+
+.. _arc.optimization.precise:
+
+Precise lifetime semantics
+--------------------------
+
+In general, ARC maintains an invariant that a retainable object pointer held in
+a ``__strong`` object will be retained for the full formal lifetime of the
+object. Objects subject to this invariant have :arc-term:`precise lifetime
+semantics`.
+
+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.
+
+.. admonition:: Rationale
+
+ 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.
+
+A local variable of retainable object owner type and automatic storage duration
+may be annotated with the ``objc_precise_lifetime`` attribute to indicate that
+it should be considered to be an object with precise lifetime semantics.
+
+.. admonition:: Rationale
+
+ 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.
+
+.. _arc.misc:
+
+Miscellaneous
+=============
+
+.. _arc.misc.special_methods:
+
+Special methods
+---------------
+
+.. _arc.misc.special_methods.retain:
+
+Memory management methods
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it contains a method definition, message send, or
+``@selector`` expression for any of the following selectors:
+
+* ``autorelease``
+* ``release``
+* ``retain``
+* ``retainCount``
+
+.. admonition:: Rationale
+
+ ``retainCount`` is banned because ARC robs it of consistent semantics. The
+ others were banned after weighing three options for how to deal with message
+ sends:
+
+ **Honoring** 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.
+
+ **Ignoring** them would badly violate user expectations about their code.
+ While it *would* 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.
+
+ **Banning** 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.
+
+ 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 :ref:`semantics
+ <arc.objects.retains>` laid out elsewhere in this document.
+
+.. _arc.misc.special_methods.dealloc:
+
+``dealloc``
+^^^^^^^^^^^
+
+A program is ill-formed if it contains a message send or ``@selector``
+expression for the selector ``dealloc``.
+
+.. admonition:: Rationale
+
+ There are no legitimate reasons to call ``dealloc`` directly.
+
+A class may provide a method definition for an instance method named
+``dealloc``. This method will be called after the final ``release`` of the
+object but before it is deallocated or any of its instance variables are
+destroyed. The superclass's implementation of ``dealloc`` will be called
+automatically when the method returns.
+
+.. admonition:: Rationale
+
+ Even though ARC destroys instance variables automatically, there are still
+ legitimate reasons to write a ``dealloc`` method, such as freeing
+ non-retainable resources. Failing to call ``[super dealloc]`` in such a
+ method is nearly always a bug. Sometimes, the object is simply trying to
+ prevent itself from being destroyed, but ``dealloc`` 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
+ ``free``; for now, this can only be supported with a ``dealloc``
+ implementation outside of ARC. Such an implementation must be very careful
+ to do all the other work that ``NSObject``'s ``dealloc`` would, which is
+ outside the scope of this document to describe.
+
+The instance variables for an ARC-compiled class will be destroyed at some
+point after control enters the ``dealloc`` 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.
+
+.. admonition:: Rationale
+
+ The traditional, non-ARC pattern for destroying instance variables is to
+ destroy them immediately before calling ``[super dealloc]``. 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
+ ``dealloc``, 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.
+
+ 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 ``dealloc``; a more
+ holistic solution is to move semantically important side-effects out of
+ ``dealloc`` and into a separate teardown phase which can rely on working with
+ well-formed objects.
+
+.. _arc.misc.autoreleasepool:
+
+``@autoreleasepool``
+--------------------
+
+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 ``@autoreleasepool`` followed by a *compound-statement*, 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 ``return`` or
+``break``), 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.
+
+``@autoreleasepool`` may be used in non-ARC translation units, with equivalent
+semantics.
+
+A program is ill-formed if it refers to the ``NSAutoreleasePool`` class.
+
+.. admonition:: Rationale
+
+ 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.
+
+.. _arc.misc.externally_retained:
+
+Externally-Retained Variables
+-----------------------------
+
+In some situations, variables with strong ownership are considered
+externally-retained by the implementation. This means that the variable is
+retained elsewhere, and therefore the implementation can elide retaining and
+releasing its value. Such a variable is implicitly ``const`` for safety. In
+contrast with ``__unsafe_unretained``, an externally-retained variable still
+behaves as a strong variable outside of initialization and destruction. For
+instance, when an externally-retained variable is captured in a block the value
+of the variable is retained and released on block capture and destruction. It
+also affects C++ features such as lambda capture, ``decltype``, and template
+argument deduction.
+
+Implicitly, the implementation assumes that the :ref:`self parameter in a
+non-init method <arc.misc.self>` and the :ref:`variable in a for-in loop
+<arc.misc.enumeration>` are externally-retained.
+
+Externally-retained semantics can also be opted into with the
+``objc_externally_retained`` attribute. This attribute can apply to strong local
+variables, functions, methods, or blocks:
+
+.. code-block:: objc
+
+ @class WobbleAmount;
+
+ @interface Widget : NSObject
+ -(void)wobble:(WobbleAmount *)amount;
+ @end
+
+ @implementation Widget
+
+ -(void)wobble:(WobbleAmount *)amount
+ __attribute__((objc_externally_retained)) {
+ // 'amount' and 'alias' aren't retained on entry, nor released on exit.
+ __attribute__((objc_externally_retained)) WobbleAmount *alias = amount;
+ }
+ @end
+
+Annotating a function with this attribute makes every parameter with strong
+retainable object pointer type externally-retained, unless the variable was
+explicitly qualified with ``__strong``. For instance, ``first_param`` is
+externally-retained (and therefore ``const``) below, but not ``second_param``:
+
+.. code-block:: objc
+
+ __attribute__((objc_externally_retained))
+ void f(NSArray *first_param, __strong NSArray *second_param) {
+ // ...
+ }
+
+You can test if your compiler has support for ``objc_externally_retained`` with
+``__has_attribute``:
+
+.. code-block:: objc
+
+ #if __has_attribute(objc_externally_retained)
+ // Use externally retained...
+ #endif
+
+.. _arc.misc.self:
+
+``self``
+--------
+
+The ``self`` parameter variable of an non-init Objective-C method is considered
+:ref:`externally-retained <arc.misc.externally_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. In an init method, ``self``
+follows the :ref:``init family rules <arc.family.semantics.init>``.
+
+.. admonition:: Rationale
+
+ The cost of retaining ``self`` 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 ``objc_externally_retained`` or
+ qualifying it with ``__unsafe_unretained``), we chose to make this optimizing
+ assumption and shift some amount of risk to the user.
+
+.. _arc.misc.enumeration:
+
+Fast enumeration iteration variables
+------------------------------------
+
+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
+implicitly :ref:`externally-retained <arc.misc.externally_retained>` so that
+objects encountered during the enumeration are not actually retained and
+released.
+
+.. admonition:: Rationale
+
+ 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 ``__strong``, which will make the variable
+ mutable again and cause the loop to retain the objects it encounters.
+
+.. _arc.misc.blocks:
+
+Blocks
+------
+
+The implicit ``const`` 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.
+
+The :ref:`inference <arc.ownership.inference>` rules apply equally to
+``__block`` variables, which is a shift in semantics from non-ARC, where
+``__block`` variables did not implicitly retain during capture.
+
+``__block`` 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.
+
+With the exception of retains done as part of initializing a ``__strong``
+parameter variable or reading a ``__weak`` variable, whenever these semantics
+call for retaining a value of block-pointer type, it has the effect of a
+``Block_copy``. The optimizer may remove such copies when it sees that the
+result is used only as an argument to a call.
+
+.. _arc.misc.exceptions:
+
+Exceptions
+----------
+
+By default in Objective C, ARC is not exception-safe for normal releases:
+
+* It does not end the lifetime of ``__strong`` variables when their scopes are
+ abnormally terminated by an exception.
+* It does not perform releases which would occur at the end of a
+ full-expression if that full-expression throws an exception.
+
+A program may be compiled with the option ``-fobjc-arc-exceptions`` in order to
+enable these, or with the option ``-fno-objc-arc-exceptions`` to explicitly
+disable them, with the last such argument "winning".
+
+.. admonition:: Rationale
+
+ 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.
+
+In Objective-C++, ``-fobjc-arc-exceptions`` is enabled by default.
+
+.. admonition:: Rationale
+
+ 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.
+
+ARC does end the lifetimes of ``__weak`` objects when an exception terminates
+their scope unless exceptions are disabled in the compiler.
+
+.. admonition:: Rationale
+
+ The consequence of a local ``__weak`` 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.
+
+.. _arc.misc.interior:
+
+Interior pointers
+-----------------
+
+An Objective-C method returning a non-retainable pointer may be annotated with
+the ``objc_returns_inner_pointer`` 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:
+
+* the last use of the returned pointer, or any pointer derived from it, in the
+ calling function or
+* the autorelease pool is restored to a previous state.
+
+.. admonition:: Rationale
+
+ 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.
+
+ 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 ``strchr``). However, the implementation
+ never need account for uses after a return from the code which calls the
+ method returning an interior pointer.
+
+As an exception, no extension is required if the receiver is loaded directly
+from a ``__strong`` object with :ref:`precise lifetime semantics
+<arc.optimization.precise>`.
+
+.. admonition:: Rationale
+
+ 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.
+
+.. _arc.misc.c-retainable:
+
+C retainable pointer types
+--------------------------
+
+A type is a :arc-term:`C retainable pointer type` if it is a pointer to
+(possibly qualified) ``void`` or a pointer to a (possibly qualifier) ``struct``
+or ``class`` type.
+
+.. admonition:: Rationale
+
+ 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.
+
+.. _arc.misc.c-retainable.audit:
+
+Auditing of C retainable pointer interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:when-revised:`[beginning Apple 4.0, LLVM 3.1]`
+
+A C function may be marked with the ``cf_audited_transfer`` 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:
+
+* A parameter of C retainable pointer type is assumed to not be consumed
+ unless it is marked with the ``cf_consumed`` attribute, and
+* A result of C retainable pointer type is assumed to not be returned retained
+ unless the function is either marked ``cf_returns_retained`` or it follows
+ the create/copy naming convention and is not marked
+ ``cf_returns_not_retained``.
+
+A function obeys the :arc-term:`create/copy` naming convention if its name
+contains as a substring:
+
+* either "Create" or "Copy" not followed by a lowercase letter, or
+* either "create" or "copy" not followed by a lowercase letter and
+ not preceded by any letter, whether uppercase or lowercase.
+
+A second attribute, ``cf_unknown_transfer``, 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 ``cf_audited_transfer`` and ``cf_unknown_transfer``.
+
+A pragma is provided to facilitate the mass annotation of interfaces:
+
+.. code-block:: objc
+
+ #pragma clang arc_cf_code_audited begin
+ ...
+ #pragma clang arc_cf_code_audited end
+
+All C functions declared within the extent of this pragma are treated as if
+annotated with the ``cf_audited_transfer`` attribute unless they otherwise have
+the ``cf_unknown_transfer`` 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.
+
+It is possible to test for all the features in this section with
+``__has_feature(arc_cf_code_audited)``.
+
+.. admonition:: Rationale
+
+ 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.
+
+.. _arc.runtime:
+
+Runtime support
+===============
+
+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++.
+
+Ownership qualification does not alter the storage requirements for objects,
+except that it is undefined behavior if a ``__weak`` object is inadequately
+aligned for an object of type ``id``. The other qualifiers may be used on
+explicitly under-aligned memory.
+
+The runtime tracks ``__weak`` objects which holds non-null values. It is
+undefined behavior to direct modify a ``__weak`` object which is being tracked
+by the runtime except through an
+:ref:`objc_storeWeak <arc.runtime.objc_storeWeak>`,
+:ref:`objc_destroyWeak <arc.runtime.objc_destroyWeak>`, or
+:ref:`objc_moveWeak <arc.runtime.objc_moveWeak>` call.
+
+The runtime must provide a number of new entrypoints which the compiler may
+emit, which are described in the remainder of this section.
+
+.. admonition:: Rationale
+
+ Several of these functions are semantically equivalent to a message send; we
+ emit calls to C functions instead because:
+
+ * the machine code to do so is significantly smaller,
+ * it is much easier to recognize the C functions in the ARC optimizer, and
+ * a sufficient sophisticated runtime may be able to avoid the message send in
+ common cases.
+
+ 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.
+
+.. _arc.runtime.objc_autorelease:
+
+``id objc_autorelease(id value);``
+----------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` 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
+``autorelease`` message.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_autoreleasePoolPop:
+
+``void objc_autoreleasePoolPop(void *pool);``
+---------------------------------------------
+
+*Precondition:* ``pool`` is the result of a previous call to
+:ref:`objc_autoreleasePoolPush <arc.runtime.objc_autoreleasePoolPush>` on the
+current thread, where neither ``pool`` nor any enclosing pool have previously
+been popped.
+
+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 ``pool``.
+
+.. _arc.runtime.objc_autoreleasePoolPush:
+
+``void *objc_autoreleasePoolPush(void);``
+-----------------------------------------
+
+Creates a new autorelease pool that is enclosed by the current pool, makes that
+the current pool, and returns an opaque "handle" to it.
+
+.. admonition:: Rationale
+
+ 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.
+
+.. _arc.runtime.objc_autoreleaseReturnValue:
+
+``id objc_autoreleaseReturnValue(id value);``
+---------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` 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
+:ref:`objc_retainAutoreleasedReturnValue
+<arc.runtime.objc_retainAutoreleasedReturnValue>` for the same object in an
+enclosing call frame. If this is not possible, the object is autoreleased as
+above.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_copyWeak:
+
+``void objc_copyWeak(id *dest, id *src);``
+------------------------------------------
+
+*Precondition:* ``src`` is a valid pointer which either contains a null pointer
+or has been registered as a ``__weak`` object. ``dest`` is a valid pointer
+which has not been registered as a ``__weak`` object.
+
+``dest`` is initialized to be equivalent to ``src``, potentially registering it
+with the runtime. Equivalent to the following code:
+
+.. code-block:: objc
+
+ void objc_copyWeak(id *dest, id *src) {
+ objc_release(objc_initWeak(dest, objc_loadWeakRetained(src)));
+ }
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``.
+
+.. _arc.runtime.objc_destroyWeak:
+
+``void objc_destroyWeak(id *object);``
+--------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+``object`` is unregistered as a weak object, if it ever was. The current value
+of ``object`` is left unspecified; otherwise, equivalent to the following code:
+
+.. code-block:: objc
+
+ void objc_destroyWeak(id *object) {
+ objc_storeWeak(object, nil);
+ }
+
+Does not need to be atomic with respect to calls to ``objc_storeWeak`` on
+``object``.
+
+.. _arc.runtime.objc_initWeak:
+
+``id objc_initWeak(id *object, id value);``
+-------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which has not been registered as
+a ``__weak`` object. ``value`` is null or a pointer to a valid object.
+
+If ``value`` is a null pointer or the object to which it points has begun
+deallocation, ``object`` is zero-initialized. Otherwise, ``object`` is
+registered as a ``__weak`` object pointing to ``value``. Equivalent to the
+following code:
+
+.. code-block:: objc
+
+ id objc_initWeak(id *object, id value) {
+ *object = nil;
+ return objc_storeWeak(object, value);
+ }
+
+Returns the value of ``object`` after the call.
+
+Does not need to be atomic with respect to calls to ``objc_storeWeak`` on
+``object``.
+
+.. _arc.runtime.objc_loadWeak:
+
+``id objc_loadWeak(id *object);``
+---------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+If ``object`` is registered as a ``__weak`` object, and the last value stored
+into ``object`` has not yet been deallocated or begun deallocation, retains and
+autoreleases that value and returns it. Otherwise returns null. Equivalent to
+the following code:
+
+.. code-block:: objc
+
+ id objc_loadWeak(id *object) {
+ return objc_autorelease(objc_loadWeakRetained(object));
+ }
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``.
+
+.. admonition:: Rationale
+
+ Loading weak references would be inherently prone to race conditions without
+ the retain.
+
+.. _arc.runtime.objc_loadWeakRetained:
+
+``id objc_loadWeakRetained(id *object);``
+-----------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.
+
+If ``object`` is registered as a ``__weak`` object, and the last value stored
+into ``object`` has not yet been deallocated or begun deallocation, retains
+that value and returns it. Otherwise returns null.
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``.
+
+.. _arc.runtime.objc_moveWeak:
+
+``void objc_moveWeak(id *dest, id *src);``
+------------------------------------------
+
+*Precondition:* ``src`` is a valid pointer which either contains a null pointer
+or has been registered as a ``__weak`` object. ``dest`` is a valid pointer
+which has not been registered as a ``__weak`` object.
+
+``dest`` is initialized to be equivalent to ``src``, potentially registering it
+with the runtime. ``src`` may then be left in its original state, in which
+case this call is equivalent to :ref:`objc_copyWeak
+<arc.runtime.objc_copyWeak>`, or it may be left as null.
+
+Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``.
+
+.. _arc.runtime.objc_release:
+
+``void objc_release(id value);``
+--------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a
+release operation exactly as if the object had been sent the ``release``
+message.
+
+.. _arc.runtime.objc_retain:
+
+``id objc_retain(id value);``
+-----------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a retain
+operation exactly as if the object had been sent the ``retain`` message.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutorelease:
+
+``id objc_retainAutorelease(id value);``
+----------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a retain
+operation followed by an autorelease operation. Equivalent to the following
+code:
+
+.. code-block:: objc
+
+ id objc_retainAutorelease(id value) {
+ return objc_autorelease(objc_retain(value));
+ }
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutoreleaseReturnValue:
+
+``id objc_retainAutoreleaseReturnValue(id value);``
+---------------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it performs a retain
+operation followed by the operation described in
+:ref:`objc_autoreleaseReturnValue <arc.runtime.objc_autoreleaseReturnValue>`.
+Equivalent to the following code:
+
+.. code-block:: objc
+
+ id objc_retainAutoreleaseReturnValue(id value) {
+ return objc_autoreleaseReturnValue(objc_retain(value));
+ }
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainAutoreleasedReturnValue:
+
+``id objc_retainAutoreleasedReturnValue(id value);``
+----------------------------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid object.
+
+If ``value`` is null, this call has no effect. Otherwise, it attempts to
+accept a hand off of a retain count from a call to
+:ref:`objc_autoreleaseReturnValue <arc.runtime.objc_autoreleaseReturnValue>` on
+``value`` in a recently-called function or something it calls. If that fails,
+it performs a retain operation exactly like :ref:`objc_retain
+<arc.runtime.objc_retain>`.
+
+Always returns ``value``.
+
+.. _arc.runtime.objc_retainBlock:
+
+``id objc_retainBlock(id value);``
+----------------------------------
+
+*Precondition:* ``value`` is null or a pointer to a valid block object.
+
+If ``value`` is null, this call has no effect. Otherwise, if the block pointed
+to by ``value`` 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 ``retain`` message.
+
+.. _arc.runtime.objc_storeStrong:
+
+``void objc_storeStrong(id *object, id value);``
+------------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer to a ``__strong`` object which is
+adequately aligned for a pointer. ``value`` is null or a pointer to a valid
+object.
+
+Performs the complete sequence for assigning to a ``__strong`` object of
+non-block type [*]_. Equivalent to the following code:
+
+.. code-block:: objc
+
+ void objc_storeStrong(id *object, id value) {
+ id oldValue = *object;
+ value = [value retain];
+ *object = value;
+ [oldValue release];
+ }
+
+.. [*] This does not imply that a ``__strong`` object of block type is an
+ invalid argument to this function. Rather it implies that an ``objc_retain``
+ and not an ``objc_retainBlock`` operation will be emitted if the argument is
+ a block.
+
+.. _arc.runtime.objc_storeWeak:
+
+``id objc_storeWeak(id *object, id value);``
+--------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object. ``value`` is null or a
+pointer to a valid object.
+
+If ``value`` is a null pointer or the object to which it points has begun
+deallocation, ``object`` is assigned null and unregistered as a ``__weak``
+object. Otherwise, ``object`` is registered as a ``__weak`` object or has its
+registration updated to point to ``value``.
+
+Returns the value of ``object`` after the call.
+
Added: www-releases/trunk/9.0.0/tools/clang/docs/_sources/Block-ABI-Apple.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/_sources/Block-ABI-Apple.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/_sources/Block-ABI-Apple.rst.txt (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/_sources/Block-ABI-Apple.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,943 @@
+==================================
+Block Implementation Specification
+==================================
+
+.. contents::
+ :local:
+
+History
+=======
+
+* 2008/7/14 - created.
+* 2008/8/21 - revised, C++.
+* 2008/9/24 - add ``NULL`` ``isa`` field to ``__block`` storage.
+* 2008/10/1 - revise block layout to use a ``static`` descriptor structure.
+* 2008/10/6 - revise block layout to use an unsigned long int flags.
+* 2008/10/28 - specify use of ``_Block_object_assign`` and
+ ``_Block_object_dispose`` for all "Object" types in helper functions.
+* 2008/10/30 - revise new layout to have invoke function in same place.
+* 2008/10/30 - add ``__weak`` support.
+* 2010/3/16 - rev for stret return, signature field.
+* 2010/4/6 - improved wording.
+* 2013/1/6 - improved wording and converted to rst.
+
+This document describes the Apple ABI implementation specification of Blocks.
+
+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.
+
+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.
+
+High Level
+==========
+
+The ABI of ``Blocks`` consist of their layout and the runtime functions required
+by the compiler. A ``Block`` consists of a structure of the following form:
+
+.. code-block:: c
+
+ struct Block_literal_1 {
+ void *isa; // initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock
+ int flags;
+ int reserved;
+ void (*invoke)(void *, ...);
+ struct Block_descriptor_1 {
+ unsigned long int reserved; // NULL
+ unsigned long int size; // sizeof(struct Block_literal_1)
+ // optional helper functions
+ void (*copy_helper)(void *dst, void *src); // IFF (1<<25)
+ void (*dispose_helper)(void *src); // IFF (1<<25)
+ // required ABI.2010.3.16
+ const char *signature; // IFF (1<<30)
+ } *descriptor;
+ // imported variables
+ };
+
+The following flags bits are in use thusly for a possible ABI.2010.3.16:
+
+.. code-block:: c
+
+ enum {
+ // Set to true on blocks that have captures (and thus are not true
+ // global blocks) but are known not to escape for various other
+ // reasons. For backward compatiblity with old runtimes, whenever
+ // BLOCK_IS_NOESCAPE is set, BLOCK_IS_GLOBAL is set too. Copying a
+ // non-escaping block returns the original block and releasing such a
+ // block is a no-op, which is exactly how global blocks are handled.
+ BLOCK_IS_NOESCAPE = (1 << 23),
+
+ BLOCK_HAS_COPY_DISPOSE = (1 << 25),
+ BLOCK_HAS_CTOR = (1 << 26), // helpers have C++ code
+ BLOCK_IS_GLOBAL = (1 << 28),
+ BLOCK_HAS_STRET = (1 << 29), // IFF BLOCK_HAS_SIGNATURE
+ BLOCK_HAS_SIGNATURE = (1 << 30),
+ };
+
+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:
+
+.. code-block:: c
+
+ switch (flags & (3<<29)) {
+ case (0<<29): 10.6.ABI, no signature field available
+ case (1<<29): 10.6.ABI, no signature field available
+ case (2<<29): ABI.2010.3.16, regular calling convention, presence of signature field
+ case (3<<29): ABI.2010.3.16, stret calling convention, presence of signature field,
+ }
+
+The signature field is not always populated.
+
+The following discussions are presented as 10.6.ABI otherwise.
+
+``Block`` literals may occur within functions where the structure is created in
+stack local memory. They may also appear as initialization expressions for
+``Block`` variables of global or ``static`` local variables.
+
+When a ``Block`` literal expression is evaluated the stack based structure is
+initialized as follows:
+
+1. A ``static`` descriptor structure is declared and initialized as follows:
+
+ a. The ``invoke`` function pointer is set to a function that takes the
+ ``Block`` structure as its first argument and the rest of the arguments (if
+ any) to the ``Block`` and executes the ``Block`` compound statement.
+
+ b. The ``size`` field is set to the size of the following ``Block`` literal
+ structure.
+
+ c. The ``copy_helper`` and ``dispose_helper`` function pointers are set to
+ respective helper functions if they are required by the ``Block`` literal.
+
+2. A stack (or global) ``Block`` literal data structure is created and
+ initialized as follows:
+
+ a. The ``isa`` field is set to the address of the external
+ ``_NSConcreteStackBlock``, which is a block of uninitialized memory supplied
+ in ``libSystem``, or ``_NSConcreteGlobalBlock`` if this is a static or file
+ level ``Block`` literal.
+
+ b. The ``flags`` field is set to zero unless there are variables imported
+ into the ``Block`` that need helper functions for program level
+ ``Block_copy()`` and ``Block_release()`` operations, in which case the
+ (1<<25) flags bit is set.
+
+As an example, the ``Block`` literal expression:
+
+.. code-block:: c
+
+ ^ { printf("hello world\n"); }
+
+would cause the following to be created on a 32-bit system:
+
+.. code-block:: c
+
+ struct __block_literal_1 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_1 *);
+ struct __block_descriptor_1 *descriptor;
+ };
+
+ void __block_invoke_1(struct __block_literal_1 *_block) {
+ printf("hello world\n");
+ }
+
+ static struct __block_descriptor_1 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ } __block_descriptor_1 = { 0, sizeof(struct __block_literal_1), __block_invoke_1 };
+
+and where the ``Block`` literal itself appears:
+
+.. code-block:: c
+
+ struct __block_literal_1 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<29), <uninitialized>,
+ __block_invoke_1,
+ &__block_descriptor_1
+ };
+
+A ``Block`` imports other ``Block`` references, ``const`` copies of other
+variables, and variables marked ``__block``. In Objective-C, variables may
+additionally be objects.
+
+When a ``Block`` literal expression is used as the initial value of a global
+or ``static`` local variable, it is initialized as follows:
+
+.. code-block:: c
+
+ struct __block_literal_1 __block_literal_1 = {
+ &_NSConcreteGlobalBlock,
+ (1<<28)|(1<<29), <uninitialized>,
+ __block_invoke_1,
+ &__block_descriptor_1
+ };
+
+that is, a different address is provided as the first value and a particular
+(1<<28) bit is set in the ``flags`` field, and otherwise it is the same as for
+stack based ``Block`` literals. This is an optimization that can be used for
+any ``Block`` literal that imports no ``const`` or ``__block`` storage
+variables.
+
+Imported Variables
+==================
+
+Variables of ``auto`` storage class are imported as ``const`` copies. Variables
+of ``__block`` storage class are imported as a pointer to an enclosing data
+structure. Global variables are simply referenced and not considered as
+imported.
+
+Imported ``const`` copy variables
+---------------------------------
+
+Automatic storage variables not marked with ``__block`` are imported as
+``const`` copies.
+
+The simplest example is that of importing a variable of type ``int``:
+
+.. code-block:: c
+
+ int x = 10;
+ void (^vv)(void) = ^{ printf("x is %d\n", x); }
+ x = 11;
+ vv();
+
+which would be compiled to:
+
+.. code-block:: c
+
+ struct __block_literal_2 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_2 *);
+ struct __block_descriptor_2 *descriptor;
+ const int x;
+ };
+
+ void __block_invoke_2(struct __block_literal_2 *_block) {
+ printf("x is %d\n", _block->x);
+ }
+
+ static struct __block_descriptor_2 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ } __block_descriptor_2 = { 0, sizeof(struct __block_literal_2) };
+
+and:
+
+.. code-block:: c
+
+ struct __block_literal_2 __block_literal_2 = {
+ &_NSConcreteStackBlock,
+ (1<<29), <uninitialized>,
+ __block_invoke_2,
+ &__block_descriptor_2,
+ x
+ };
+
+In summary, scalars, structures, unions, and function pointers are generally
+imported as ``const`` copies with no need for helper functions.
+
+Imported ``const`` copy of ``Block`` reference
+----------------------------------------------
+
+The first case where copy and dispose helper functions are required is for the
+case of when a ``Block`` itself is imported. In this case both a
+``copy_helper`` function and a ``dispose_helper`` function are needed. The
+``copy_helper`` 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 ``Block``. The
+runtime functions are all described in :ref:`RuntimeHelperFunctions`.
+
+A quick example:
+
+.. code-block:: c
+
+ void (^existingBlock)(void) = ...;
+ void (^vv)(void) = ^{ existingBlock(); }
+ vv();
+
+ struct __block_literal_3 {
+ ...; // existing block
+ };
+
+ struct __block_literal_4 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_4 *);
+ struct __block_literal_3 *const existingBlock;
+ };
+
+ void __block_invoke_4(struct __block_literal_2 *_block) {
+ __block->existingBlock->invoke(__block->existingBlock);
+ }
+
+ void __block_copy_4(struct __block_literal_4 *dst, struct __block_literal_4 *src) {
+ //_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0);
+ _Block_object_assign(&dst->existingBlock, src->existingBlock, BLOCK_FIELD_IS_BLOCK);
+ }
+
+ void __block_dispose_4(struct __block_literal_4 *src) {
+ // was _Block_destroy
+ _Block_object_dispose(src->existingBlock, BLOCK_FIELD_IS_BLOCK);
+ }
+
+ static struct __block_descriptor_4 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_4 *dst, struct __block_literal_4 *src);
+ void (*dispose_helper)(struct __block_literal_4 *);
+ } __block_descriptor_4 = {
+ 0,
+ sizeof(struct __block_literal_4),
+ __block_copy_4,
+ __block_dispose_4,
+ };
+
+and where said ``Block`` is used:
+
+.. code-block:: c
+
+ struct __block_literal_4 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<29), <uninitialized>
+ __block_invoke_4,
+ & __block_descriptor_4
+ existingBlock,
+ };
+
+Importing ``__attribute__((NSObject))`` variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GCC introduces ``__attribute__((NSObject))`` 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. ``CFStringRef``, ``CFArrayRef``,
+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
+``_Block_object_assign`` runtime helper function and in the dispose helper the
+``_Block_object_dispose`` runtime helper function should be called.
+
+For example, ``Block`` foo in the following:
+
+.. code-block:: c
+
+ struct Opaque *__attribute__((NSObject)) objectPointer = ...;
+ ...
+ void (^foo)(void) = ^{ CFPrint(objectPointer); };
+
+would have the following helper functions generated:
+
+.. code-block:: c
+
+ void __block_copy_foo(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+ _Block_object_assign(&dst->objectPointer, src-> objectPointer, BLOCK_FIELD_IS_OBJECT);
+ }
+
+ void __block_dispose_foo(struct __block_literal_5 *src) {
+ _Block_object_dispose(src->objectPointer, BLOCK_FIELD_IS_OBJECT);
+ }
+
+Imported ``__block`` marked variables
+-------------------------------------
+
+Layout of ``__block`` marked variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The compiler must embed variables that are marked ``__block`` in a specialized
+structure of the form:
+
+.. code-block:: c
+
+ struct _block_byref_foo {
+ void *isa;
+ struct Block_byref *forwarding;
+ int flags; //refcount;
+ int size;
+ typeof(marked_variable) marked_variable;
+ };
+
+Variables of certain types require helper functions for when ``Block_copy()``
+and ``Block_release()`` are performed upon a referencing ``Block``. At the "C"
+level only variables that are of type ``Block`` or ones that have
+``__attribute__((NSObject))`` 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:
+
+.. code-block:: c
+
+ struct _block_byref_foo {
+ void *isa;
+ struct _block_byref_foo *forwarding;
+ int flags; //refcount;
+ int size;
+ // helper functions called via Block_copy() and Block_release()
+ void (*byref_keep)(void *dst, void *src);
+ void (*byref_dispose)(void *);
+ typeof(marked_variable) marked_variable;
+ };
+
+The structure is initialized such that:
+
+ a. The ``forwarding`` pointer is set to the beginning of its enclosing
+ structure.
+
+ b. The ``size`` field is initialized to the total size of the enclosing
+ structure.
+
+ c. The ``flags`` field is set to either 0 if no helper functions are needed
+ or (1<<25) if they are.
+
+ d. The helper functions are initialized (if present).
+
+ e. The variable itself is set to its initial value.
+
+ f. The ``isa`` field is set to ``NULL``.
+
+Access to ``__block`` variables from within its lexical scope
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to "move" the variable to the heap upon a ``copy_helper`` operation the
+compiler must rewrite access to such a variable to be indirect through the
+structures ``forwarding`` pointer. For example:
+
+.. code-block:: c
+
+ int __block i = 10;
+ i = 11;
+
+would be rewritten to be:
+
+.. code-block:: c
+
+ struct _block_byref_i {
+ void *isa;
+ struct _block_byref_i *forwarding;
+ int flags; //refcount;
+ int size;
+ int captured_i;
+ } i = { NULL, &i, 0, sizeof(struct _block_byref_i), 10 };
+
+ i.forwarding->captured_i = 11;
+
+In the case of a ``Block`` reference variable being marked ``__block`` the
+helper code generated must use the ``_Block_object_assign`` and
+``_Block_object_dispose`` routines supplied by the runtime to make the
+copies. For example:
+
+.. code-block:: c
+
+ __block void (voidBlock)(void) = blockA;
+ voidBlock = blockB;
+
+would translate into:
+
+.. code-block:: c
+
+ struct _block_byref_voidBlock {
+ void *isa;
+ struct _block_byref_voidBlock *forwarding;
+ int flags; //refcount;
+ int size;
+ void (*byref_keep)(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src);
+ void (*byref_dispose)(struct _block_byref_voidBlock *);
+ void (^captured_voidBlock)(void);
+ };
+
+ void _block_byref_keep_helper(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) {
+ //_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0);
+ _Block_object_assign(&dst->captured_voidBlock, src->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER);
+ }
+
+ void _block_byref_dispose_helper(struct _block_byref_voidBlock *param) {
+ //_Block_destroy(param->captured_voidBlock, 0);
+ _Block_object_dispose(param->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER)}
+
+and:
+
+.. code-block:: c
+
+ struct _block_byref_voidBlock voidBlock = {( .forwarding=&voidBlock, .flags=(1<<25), .size=sizeof(struct _block_byref_voidBlock *),
+ .byref_keep=_block_byref_keep_helper, .byref_dispose=_block_byref_dispose_helper,
+ .captured_voidBlock=blockA )};
+
+ voidBlock.forwarding->captured_voidBlock = blockB;
+
+Importing ``__block`` variables into ``Blocks``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``Block`` that uses a ``__block`` variable in its compound statement body must
+import the variable and emit ``copy_helper`` and ``dispose_helper`` helper
+functions that, in turn, call back into the runtime to actually copy or release
+the ``byref`` data block using the functions ``_Block_object_assign`` and
+``_Block_object_dispose``.
+
+For example:
+
+.. code-block:: c
+
+ int __block i = 2;
+ functioncall(^{ i = 10; });
+
+would translate to:
+
+.. code-block:: c
+
+ struct _block_byref_i {
+ void *isa; // set to NULL
+ struct _block_byref_voidBlock *forwarding;
+ int flags; //refcount;
+ int size;
+ void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src);
+ void (*byref_dispose)(struct _block_byref_i *);
+ int captured_i;
+ };
+
+
+ struct __block_literal_5 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_5 *);
+ struct __block_descriptor_5 *descriptor;
+ struct _block_byref_i *i_holder;
+ };
+
+ void __block_invoke_5(struct __block_literal_5 *_block) {
+ _block->forwarding->captured_i = 10;
+ }
+
+ void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+ //_Block_byref_assign_copy(&dst->captured_i, src->captured_i);
+ _Block_object_assign(&dst->captured_i, src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER);
+ }
+
+ void __block_dispose_5(struct __block_literal_5 *src) {
+ //_Block_byref_release(src->captured_i);
+ _Block_object_dispose(src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER);
+ }
+
+ static struct __block_descriptor_5 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src);
+ void (*dispose_helper)(struct __block_literal_5 *);
+ } __block_descriptor_5 = { 0, sizeof(struct __block_literal_5) __block_copy_5, __block_dispose_5 };
+
+and:
+
+.. code-block:: c
+
+ struct _block_byref_i i = {( .isa=NULL, .forwarding=&i, .flags=0, .size=sizeof(struct _block_byref_i), .captured_i=2 )};
+ struct __block_literal_5 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<29), <uninitialized>,
+ __block_invoke_5,
+ &__block_descriptor_5,
+ &i,
+ };
+
+Importing ``__attribute__((NSObject))`` ``__block`` variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``__block`` variable that is also marked ``__attribute__((NSObject))`` should
+have ``byref_keep`` and ``byref_dispose`` helper functions that use
+``_Block_object_assign`` and ``_Block_object_dispose``.
+
+``__block`` escapes
+^^^^^^^^^^^^^^^^^^^
+
+Because ``Blocks`` referencing ``__block`` variables may have ``Block_copy()``
+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
+``__block`` variables at all escapes or terminations of their scope. The call
+should be:
+
+.. code-block:: c
+
+ _Block_object_dispose(&_block_byref_foo, BLOCK_FIELD_IS_BYREF);
+
+Nesting
+^^^^^^^
+
+``Blocks`` may contain ``Block`` literal expressions. Any variables used within
+inner blocks are imported into all enclosing ``Block`` scopes even if the
+variables are not used. This includes ``const`` imports as well as ``__block``
+variables.
+
+Objective C Extensions to ``Blocks``
+====================================
+
+Importing Objects
+-----------------
+
+Objects should be treated as ``__attribute__((NSObject))`` variables; all
+``copy_helper``, ``dispose_helper``, ``byref_keep``, and ``byref_dispose``
+helper functions should use ``_Block_object_assign`` and
+``_Block_object_dispose``. There should be no code generated that uses
+``*-retain`` or ``*-release`` methods.
+
+``Blocks`` as Objects
+---------------------
+
+The compiler will treat ``Blocks`` 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.
+
+``__weak __block`` Support
+--------------------------
+
+Objective-C (and Objective-C++) support the ``__weak`` attribute on ``__block``
+variables. Under normal circumstances the compiler uses the Objective-C runtime
+helper support functions ``objc_assign_weak`` and ``objc_read_weak``. Both
+should continue to be used for all reads and writes of ``__weak __block``
+variables:
+
+.. code-block:: c
+
+ objc_read_weak(&block->byref_i->forwarding->i)
+
+The ``__weak`` variable is stored in a ``_block_byref_foo`` structure and the
+``Block`` has copy and dispose helpers for this structure that call:
+
+.. code-block:: c
+
+ _Block_object_assign(&dest->_block_byref_i, src-> _block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF);
+
+and:
+
+.. code-block:: c
+
+ _Block_object_dispose(src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF);
+
+In turn, the ``block_byref`` copy support helpers distinguish between whether
+the ``__block`` variable is a ``Block`` or not and should either call:
+
+.. code-block:: c
+
+ _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_OBJECT | BLOCK_BYREF_CALLER);
+
+for something declared as an object or:
+
+.. code-block:: c
+
+ _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER);
+
+for something declared as a ``Block``.
+
+A full example follows:
+
+.. code-block:: c
+
+ __block __weak id obj = <initialization expression>;
+ functioncall(^{ [obj somemessage]; });
+
+would translate to:
+
+.. code-block:: c
+
+ struct _block_byref_obj {
+ void *isa; // uninitialized
+ struct _block_byref_obj *forwarding;
+ int flags; //refcount;
+ int size;
+ void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src);
+ void (*byref_dispose)(struct _block_byref_i *);
+ id captured_obj;
+ };
+
+ void _block_byref_obj_keep(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) {
+ //_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0);
+ _Block_object_assign(&dst->captured_obj, src->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER);
+ }
+
+ void _block_byref_obj_dispose(struct _block_byref_voidBlock *param) {
+ //_Block_destroy(param->captured_obj, 0);
+ _Block_object_dispose(param->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER);
+ };
+
+for the block ``byref`` part and:
+
+.. code-block:: c
+
+ struct __block_literal_5 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_5 *);
+ struct __block_descriptor_5 *descriptor;
+ struct _block_byref_obj *byref_obj;
+ };
+
+ void __block_invoke_5(struct __block_literal_5 *_block) {
+ [objc_read_weak(&_block->byref_obj->forwarding->captured_obj) somemessage];
+ }
+
+ void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+ //_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj);
+ _Block_object_assign(&dst->byref_obj, src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK);
+ }
+
+ void __block_dispose_5(struct __block_literal_5 *src) {
+ //_Block_byref_release(src->byref_obj);
+ _Block_object_dispose(src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK);
+ }
+
+ static struct __block_descriptor_5 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src);
+ void (*dispose_helper)(struct __block_literal_5 *);
+ } __block_descriptor_5 = { 0, sizeof(struct __block_literal_5), __block_copy_5, __block_dispose_5 };
+
+and within the compound statement:
+
+.. code-block:: c
+
+ truct _block_byref_obj obj = {( .forwarding=&obj, .flags=(1<<25), .size=sizeof(struct _block_byref_obj),
+ .byref_keep=_block_byref_obj_keep, .byref_dispose=_block_byref_obj_dispose,
+ .captured_obj = <initialization expression> )};
+
+ truct __block_literal_5 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<29), <uninitialized>,
+ __block_invoke_5,
+ &__block_descriptor_5,
+ &obj, // a reference to the on-stack structure containing "captured_obj"
+ };
+
+
+ functioncall(_block_literal->invoke(&_block_literal));
+
+C++ Support
+===========
+
+Within a block stack based C++ objects are copied into ``const`` 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
+``Block_copy()`` 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 ``const`` constructed copies, and similarly
+should call the destructor in the destroy routine.
+
+As an example, suppose a C++ class ``FOO`` existed with a copy constructor.
+Within a code block a stack version of a ``FOO`` object is declared and used
+within a ``Block`` literal expression:
+
+.. code-block:: c++
+
+ {
+ FOO foo;
+ void (^block)(void) = ^{ printf("%d\n", foo.value()); };
+ }
+
+The compiler would synthesize:
+
+.. code-block:: c++
+
+ struct __block_literal_10 {
+ void *isa;
+ int flags;
+ int reserved;
+ void (*invoke)(struct __block_literal_10 *);
+ struct __block_descriptor_10 *descriptor;
+ const FOO foo;
+ };
+
+ void __block_invoke_10(struct __block_literal_10 *_block) {
+ printf("%d\n", _block->foo.value());
+ }
+
+ void __block_literal_10(struct __block_literal_10 *dst, struct __block_literal_10 *src) {
+ FOO_ctor(&dst->foo, &src->foo);
+ }
+
+ void __block_dispose_10(struct __block_literal_10 *src) {
+ FOO_dtor(&src->foo);
+ }
+
+ static struct __block_descriptor_10 {
+ unsigned long int reserved;
+ unsigned long int Block_size;
+ void (*copy_helper)(struct __block_literal_10 *dst, struct __block_literal_10 *src);
+ void (*dispose_helper)(struct __block_literal_10 *);
+ } __block_descriptor_10 = { 0, sizeof(struct __block_literal_10), __block_copy_10, __block_dispose_10 };
+
+and the code would be:
+
+.. code-block:: c++
+
+ {
+ FOO foo;
+ comp_ctor(&foo); // default constructor
+ struct __block_literal_10 _block_literal = {
+ &_NSConcreteStackBlock,
+ (1<<25)|(1<<26)|(1<<29), <uninitialized>,
+ __block_invoke_10,
+ &__block_descriptor_10,
+ };
+ comp_ctor(&_block_literal->foo, &foo); // const copy into stack version
+ struct __block_literal_10 &block = &_block_literal; // assign literal to block variable
+ block->invoke(block); // invoke block
+ comp_dtor(&_block_literal->foo); // destroy stack version of const block copy
+ comp_dtor(&foo); // destroy original version
+ }
+
+
+C++ objects stored in ``__block`` storage start out on the stack in a
+``block_byref`` data structure as do other variables. Such objects (if not
+``const`` objects) must support a regular copy constructor. The ``block_byref``
+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 ``block_byref`` 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
+``block_byref`` heap data structure. For example,
+
+.. code-block:: c++
+
+ __block FOO blockStorageFoo;
+
+requires the normal constructor for the embedded ``blockStorageFoo`` object:
+
+.. code-block:: c++
+
+ FOO_ctor(& _block_byref_blockStorageFoo->blockStorageFoo);
+
+and at scope termination the destructor:
+
+.. code-block:: c++
+
+ FOO_dtor(& _block_byref_blockStorageFoo->blockStorageFoo);
+
+Note that the forwarding indirection is *NOT* used.
+
+The compiler would need to generate (if used from a block literal) the following
+copy/dispose helpers:
+
+.. code-block:: c++
+
+ void _block_byref_obj_keep(struct _block_byref_blockStorageFoo *dst, struct _block_byref_blockStorageFoo *src) {
+ FOO_ctor(&dst->blockStorageFoo, &src->blockStorageFoo);
+ }
+
+ void _block_byref_obj_dispose(struct _block_byref_blockStorageFoo *src) {
+ FOO_dtor(&src->blockStorageFoo);
+ }
+
+for the appropriately named constructor and destructor for the class/struct
+``FOO``.
+
+To support member variable and function access the compiler will synthesize a
+``const`` pointer to a block version of the ``this`` pointer.
+
+.. _RuntimeHelperFunctions:
+
+Runtime Helper Functions
+========================
+
+The runtime helper functions are described in
+``/usr/local/include/Block_private.h``. To summarize their use, a ``Block``
+requires copy/dispose helpers if it imports any block variables, ``__block``
+storage variables, ``__attribute__((NSObject))`` variables, or C++ ``const``
+copied objects with constructor/destructors. The (1<<26) bit is set and
+functions are generated.
+
+The block copy helper function should, for each of the variables of the type
+mentioned above, call:
+
+.. code-block:: c
+
+ _Block_object_assign(&dst->target, src->target, BLOCK_FIELD_<apropos>);
+
+in the copy helper and:
+
+.. code-block:: c
+
+ _Block_object_dispose(->target, BLOCK_FIELD_<apropos>);
+
+in the dispose helper where ``<apropos>`` is:
+
+.. code-block:: c
+
+ enum {
+ BLOCK_FIELD_IS_OBJECT = 3, // id, NSObject, __attribute__((NSObject)), block, ...
+ BLOCK_FIELD_IS_BLOCK = 7, // a block variable
+ BLOCK_FIELD_IS_BYREF = 8, // the on stack structure holding the __block variable
+
+ BLOCK_FIELD_IS_WEAK = 16, // declared __weak
+
+ BLOCK_BYREF_CALLER = 128, // called from byref copy/dispose helpers
+ };
+
+and of course the constructors/destructors for ``const`` copied C++ objects.
+
+The ``block_byref`` data structure similarly requires copy/dispose helpers for
+block variables, ``__attribute__((NSObject))`` variables, or C++ ``const``
+copied objects with constructor/destructors, and again the (1<<26) bit is set
+and functions are generated in the same manner.
+
+Under ObjC we allow ``__weak`` as an attribute on ``__block`` variables, and
+this causes the addition of ``BLOCK_FIELD_IS_WEAK`` orred onto the
+``BLOCK_FIELD_IS_BYREF`` flag when copying the ``block_byref`` structure in the
+``Block`` copy helper, and onto the ``BLOCK_FIELD_<apropos>`` field within the
+``block_byref`` copy/dispose helper calls.
+
+The prototypes, and summary, of the helper functions are:
+
+.. code-block:: c
+
+ /* Certain field types require runtime assistance when being copied to the
+ heap. The following function is used to copy fields of types: blocks,
+ pointers to byref structures, and objects (including
+ __attribute__((NSObject)) pointers. BLOCK_FIELD_IS_WEAK is orthogonal to
+ the other choices which are mutually exclusive. Only in a Block copy
+ helper will one see BLOCK_FIELD_IS_BYREF.
+ */
+ void _Block_object_assign(void *destAddr, const void *object, const int flags);
+
+ /* Similarly a compiler generated dispose helper needs to call back for each
+ field of the byref data structure. (Currently the implementation only
+ packs one field into the byref structure but in principle there could be
+ more). The same flags used in the copy helper should be used for each
+ call generated to this function:
+ */
+ void _Block_object_dispose(const void *object, const int flags);
+
+Copyright
+=========
+
+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:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+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.
Added: www-releases/trunk/9.0.0/tools/clang/docs/_sources/BlockLanguageSpec.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/_sources/BlockLanguageSpec.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/_sources/BlockLanguageSpec.rst.txt (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/_sources/BlockLanguageSpec.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,361 @@
+
+.. role:: block-term
+
+=================================
+Language Specification for Blocks
+=================================
+
+.. contents::
+ :local:
+
+Revisions
+=========
+
+- 2008/2/25 --- created
+- 2008/7/28 --- revised, ``__block`` syntax
+- 2008/8/13 --- revised, Block globals
+- 2008/8/21 --- revised, C++ elaboration
+- 2008/11/1 --- revised, ``__weak`` support
+- 2009/1/12 --- revised, explicit return types
+- 2009/2/10 --- revised, ``__block`` objects need retain
+
+Overview
+========
+
+A new derived type is introduced to C and, by extension, Objective-C,
+C++, and Objective-C++
+
+The Block Type
+==============
+
+Like function types, the :block-term:`Block type` 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.
+
+The abstract declarator,
+
+.. code-block:: c
+
+ int (^)(char, float)
+
+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.
+
+Block Variable Declarations
+===========================
+
+A :block-term:`variable with Block type` is declared using function
+pointer style notation substituting ``^`` for ``*``. The following are
+valid Block variable declarations:
+
+.. code-block:: c
+
+ void (^blockReturningVoidWithVoidArgument)(void);
+ int (^blockReturningIntWithIntAndCharArguments)(int, char);
+ void (^arrayOfTenBlocksReturningVoidWithIntArgument[10])(int);
+
+Variadic ``...`` 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.
+
+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 ``*``, and thus a Block's size may not be
+computed at compile time. [sizeof.c]
+
+Block Literal Expressions
+=========================
+
+A :block-term:`Block literal expression` produces a reference to a
+Block. It is introduced by the use of the ``^`` token as a unary
+operator.
+
+.. code-block:: c
+
+ Block_literal_expression ::= ^ block_decl compound_statement_body
+ block_decl ::=
+ block_decl ::= parameter_list
+ block_decl ::= type_expression
+
+where type expression is extended to allow ``^`` as a Block reference
+(pointer) where ``*`` is allowed as a function reference (pointer).
+
+The following Block literal:
+
+.. code-block:: c
+
+ ^ void (void) { printf("hello world\n"); }
+
+produces a reference to a Block with no arguments with no return value.
+
+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.
+
+If the return type is omitted and the argument list is ``( void )``,
+the ``( void )`` argument list may also be omitted.
+
+So:
+
+.. code-block:: c
+
+ ^ ( void ) { printf("hello world\n"); }
+
+and:
+
+.. code-block:: c
+
+ ^ { printf("hello world\n"); }
+
+are exactly equivalent constructs for the same expression.
+
+The type_expression extends C expression parsing to accommodate Block
+reference declarations as it accommodates function pointer
+declarations.
+
+Given:
+
+.. code-block:: c
+
+ typedef int (*pointerToFunctionThatReturnsIntWithCharArg)(char);
+ pointerToFunctionThatReturnsIntWithCharArg functionPointer;
+ ^ pointerToFunctionThatReturnsIntWithCharArg (float x) { return functionPointer; }
+
+and:
+
+.. code-block:: c
+
+ ^ int ((*)(float x))(char) { return functionPointer; }
+
+are equivalent expressions, as is:
+
+.. code-block:: c
+
+ ^(float x) { return functionPointer; }
+
+[returnfunctionptr.c]
+
+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]
+
+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.
+
+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:
+
+.. code-block:: c
+
+ (void) foo;
+
+This matters when capturing the variable has side-effects, as it can
+in Objective-C or C++.
+
+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]
+
+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.
+
+A Block literal expression may be used as the initialization value for
+Block variables at global or local static scope.
+
+The Invoke Operator
+===================
+
+Blocks are :block-term:`invoked` 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:
+
+.. code-block:: c
+
+ int (^x)(char);
+ void (^z)(void);
+ int (^(*y))(char) = &x;
+
+the following are all legal Block invocations:
+
+.. code-block:: c
+
+ x('a');
+ (*y)('a');
+ (true ? x : *y)('a')
+
+The Copy and Release Operations
+===============================
+
+The compiler and runtime provide :block-term:`copy` and
+:block-term:`release` operations for Block references that create and,
+in matched use, release allocated storage for referenced Blocks.
+
+The copy operation ``Block_copy()`` is styled as a function that takes
+an arbitrary Block reference and returns a Block reference of the same
+type. The release operation, ``Block_release()``, 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.
+
+
+The ``__block`` Storage Qualifier
+=================================
+
+In addition to the new Block type we also introduce a new storage
+qualifier, :block-term:`__block`, for local variables. [testme: a
+__block declaration within a block literal] The ``__block`` storage
+qualifier is mutually exclusive to the existing local storage
+qualifiers auto, register, and static. [testme] Variables qualified by
+``__block`` 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.
+
+In the case where a ``__block`` variable is a Block one must assume
+that the ``__block`` 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 ``Block_copy`` operation). Despite this
+there is no provision to do a ``Block_copy`` or a ``Block_release`` 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.
+
+
+Control Flow
+============
+
+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 *normally* in that when
+thrown they pop stack frames until a catch clause is found.
+
+
+Objective-C Extensions
+======================
+
+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.
+
+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 ``__weak`` locations
+if garbage collection is enabled.
+
+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.
+
+The :block-term:`Block_copy` 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 ``__block`` storage type are assumed to hold
+normal pointers with no provision for retain and release messages.
+
+Foundation defines (and supplies) ``-copy`` and ``-release`` methods for
+Blocks.
+
+In the Objective-C and Objective-C++ languages, we allow the
+``__weak`` specifier for ``__block`` 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.
+
+In garbage collected environments, the ``__weak`` variable is set to
+nil when the object it references is collected, as long as the
+``__block`` variable resides in the heap (either by default or via
+``Block_copy()``). The initial Apple implementation does in fact
+start ``__block`` variables on the stack and migrate them to the heap
+only as a result of a ``Block_copy()`` operation.
+
+It is a runtime error to attempt to assign a reference to a
+stack-based Block into any storage marked ``__weak``, including
+``__weak`` ``__block`` variables.
+
+
+C++ Extensions
+==============
+
+Block literal expressions within functions are extended to allow const
+use of C++ objects, pointers, or references held in automatic storage.
+
+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.
+
+For example, given a class Foo:
+
+.. code-block:: c
+
+ Foo foo;
+ Foo &fooRef = foo;
+ Foo *fooPtr = &foo;
+
+A Block that referenced these variables would import the variables as
+const variations:
+
+.. code-block:: c
+
+ const Foo block_foo = foo;
+ Foo &block_fooRef = fooRef;
+ Foo *const block_fooPtr = fooPtr;
+
+Captured variables are copied into the Block at the instant of
+evaluating the Block literal expression. They are also copied when
+calling ``Block_copy()`` 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.
+
+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.
+
+Variables declared as residing in ``__block`` 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 ``Block_copy()`` operation. When copied
+from the stack, ``__block`` variables are copied using their normal
+qualification (i.e. without adding const). In C++11, ``__block``
+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.
+
+References to ``this``, as well as references to non-static members of
+any enclosing class, are evaluated by capturing ``this`` just like a
+normal variable of C pointer type.
+
+Member variables that are Blocks may not be overloaded by the types of
+their arguments.
Added: www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangCheck.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangCheck.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangCheck.rst.txt (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangCheck.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,36 @@
+==========
+ClangCheck
+==========
+
+`ClangCheck` is a small wrapper around :doc:`LibTooling` which can be used to
+do basic error checking and AST dumping.
+
+.. code-block:: console
+
+ $ cat <<EOF > snippet.cc
+ > void f() {
+ > int a = 0
+ > }
+ > EOF
+ $ ~/clang/build/bin/clang-check snippet.cc -ast-dump --
+ Processing: /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc.
+ /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: error: expected ';' at end of
+ declaration
+ int a = 0
+ ^
+ ;
+ (TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>>
+ (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128')
+ (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned __int128')
+ (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list '__va_list_tag [1]')
+ (FunctionDecl 0x7ff3a302a8d0 </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> f 'void (void)'
+ (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1>
+ (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1>
+ (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int'
+ (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0))))))
+ 1 error generated.
+ Error while processing snippet.cc.
+
+The '--' at the end is important as it prevents :program:`clang-check` from
+searching for a compilation database. For more information on how to setup and
+use :program:`clang-check` in a project, see :doc:`HowToSetupToolingForLLVM`.
Added: www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangCommandLineReference.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangCommandLineReference.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangCommandLineReference.rst.txt (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangCommandLineReference.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,3318 @@
+..
+ -------------------------------------------------------------------
+ NOTE: This file is automatically generated by running clang-tblgen
+ -gen-opt-docs. Do not edit this file by hand!!
+ -------------------------------------------------------------------
+
+=====================================
+Clang command line argument reference
+=====================================
+.. contents::
+ :local:
+
+Introduction
+============
+
+This page lists the command line arguments currently supported by the
+GCC-compatible ``clang`` and ``clang++`` drivers.
+
+
+.. program:: clang
+.. option:: -B<dir>, --prefix <arg>, --prefix=<arg>
+
+Add <dir> to search path for binaries and object files used implicitly
+
+.. option:: -F<arg>
+
+Add directory to framework include search path
+
+.. option:: -ObjC
+
+Treat source input files as Objective-C inputs
+
+.. program:: clang1
+.. option:: -ObjC++
+.. program:: clang
+
+Treat source input files as Objective-C++ inputs
+
+.. option:: -Qn, -fno-ident
+
+Do not emit metadata containing compiler name and version
+
+.. option:: -Qunused-arguments
+
+Don't emit warning for unused driver arguments
+
+.. option:: -Qy, -fident
+
+Emit metadata containing compiler name and version
+
+.. option:: -Wa,<arg>,<arg2>...
+
+Pass the comma separated arguments in <arg> to the assembler
+
+.. option:: -Wlarge-by-value-copy=<arg>
+
+.. option:: -Xarch\_<arg1> <arg2>
+
+.. option:: -Xcuda-fatbinary <arg>
+
+Pass <arg> to fatbinary invocation
+
+.. option:: -Xcuda-ptxas <arg>
+
+Pass <arg> to the ptxas assembler
+
+.. option:: -Xopenmp-target <arg>
+
+Pass <arg> to the target offloading toolchain.
+
+.. program:: clang1
+.. option:: -Xopenmp-target=<triple> <arg>
+.. program:: clang
+
+Pass <arg> to the target offloading toolchain identified by <triple>.
+
+.. option:: -Z<arg>
+
+.. option:: -a<arg>, --profile-blocks
+
+.. option:: -all\_load
+
+.. option:: -allowable\_client <arg>
+
+.. option:: --analyze
+
+Run the static analyzer
+
+.. option:: --analyze-auto
+
+.. option:: --analyzer-no-default-checks
+
+.. option:: --analyzer-output<arg>
+
+Static analyzer report output format (html\|plist\|plist-multi-file\|plist-html\|text).
+
+.. option:: -ansi, --ansi
+
+.. option:: -arch <arg>
+
+.. program:: clang1
+.. option:: -arch\_errors\_fatal
+.. program:: clang
+
+.. program:: clang2
+.. option:: -arch\_only <arg>
+.. program:: clang
+
+.. option:: -arcmt-migrate-emit-errors
+
+Emit ARC errors even if the migrator can fix them
+
+.. option:: -arcmt-migrate-report-output <arg>
+
+Output path for the plist report
+
+.. option:: --autocomplete=<arg>
+
+.. option:: -bind\_at\_load
+
+.. option:: -bundle
+
+.. program:: clang1
+.. option:: -bundle\_loader <arg>
+.. program:: clang
+
+.. option:: -cfguard
+
+Emit tables required for Windows Control Flow Guard.
+
+.. option:: -client\_name<arg>
+
+.. option:: -compatibility\_version<arg>
+
+.. option:: --config <arg>
+
+Specifies configuration file
+
+.. option:: --constant-cfstrings
+
+.. option:: -coverage, --coverage
+
+.. option:: --cuda-compile-host-device
+
+Compile CUDA code for both host and device (default). Has no effect on non-CUDA compilations.
+
+.. option:: --cuda-device-only
+
+Compile CUDA code for device only
+
+.. option:: --cuda-gpu-arch=<arg>, --no-cuda-gpu-arch=<arg>
+
+CUDA GPU architecture (e.g. sm\_35). May be specified more than once.
+
+.. option:: --cuda-host-only
+
+Compile CUDA code for host only. Has no effect on non-CUDA compilations.
+
+.. option:: --cuda-include-ptx=<arg>, --no-cuda-include-ptx=<arg>
+
+Include PTX for the following GPU architecture (e.g. sm\_35) or 'all'. May be specified more than once.
+
+.. option:: --cuda-noopt-device-debug, --no-cuda-noopt-device-debug
+
+Enable device-side debug info generation. Disables ptxas optimizations.
+
+.. option:: -current\_version<arg>
+
+.. option:: -dead\_strip
+
+.. option:: -dependency-dot <arg>
+
+Filename to write DOT-formatted header dependencies to
+
+.. option:: -dependency-file <arg>
+
+Filename (or -) to write dependency output to
+
+.. option:: -dumpmachine
+
+.. option:: -dumpversion
+
+.. option:: --dyld-prefix=<arg>, --dyld-prefix <arg>
+
+.. option:: -dylib\_file <arg>
+
+.. option:: -dylinker
+
+.. program:: clang1
+.. option:: -dylinker\_install\_name<arg>
+.. program:: clang
+
+.. option:: -dynamic
+
+.. option:: -dynamiclib
+
+.. option:: -emit-ast
+
+Emit Clang AST files for source inputs
+
+.. option:: -enable-trivial-auto-var-init-zero-knowing-it-will-be-removed-from-clang<arg>
+
+Trivial automatic variable initialization to zero is only here for benchmarks, it'll eventually be removed, and I'm OK with that because I'm only using it to benchmark
+
+.. option:: -exported\_symbols\_list <arg>
+
+.. option:: -faligned-new=<arg>
+
+.. option:: -fcuda-approx-transcendentals, -fno-cuda-approx-transcendentals
+
+Use approximate transcendental functions
+
+.. option:: -fcuda-flush-denormals-to-zero, -fno-cuda-flush-denormals-to-zero
+
+Flush denormal floating point values to zero in CUDA device mode.
+
+.. option:: -fcuda-short-ptr, -fno-cuda-short-ptr
+
+Use 32-bit pointers for accessing const/local/shared address spaces.
+
+.. option:: -ffixed-r19
+
+Reserve register r19 (Hexagon only)
+
+.. option:: -fgpu-rdc, -fcuda-rdc, -fno-gpu-rdc
+
+Generate relocatable device code, also known as separate compilation mode.
+
+.. option:: -fheinous-gnu-extensions
+
+.. option:: -flat\_namespace
+
+.. option:: -fopenmp-targets=<arg1>,<arg2>...
+
+Specify comma-separated list of triples OpenMP offloading targets to be supported
+
+.. option:: -force\_cpusubtype\_ALL
+
+.. program:: clang1
+.. option:: -force\_flat\_namespace
+.. program:: clang
+
+.. program:: clang2
+.. option:: -force\_load <arg>
+.. program:: clang
+
+.. option:: -framework <arg>
+
+.. option:: -frtlib-add-rpath, -fno-rtlib-add-rpath
+
+Add -rpath with architecture-specific resource directory to the linker flags
+
+.. option:: --gcc-toolchain=<arg>, -gcc-toolchain <arg>
+
+Use the gcc toolchain at the given directory
+
+.. option:: -gcodeview
+
+Generate CodeView debug information
+
+.. option:: -gcodeview-ghash, -gno-codeview-ghash
+
+Emit type record hashes in a .debug$H section
+
+.. option:: -headerpad\_max\_install\_names<arg>
+
+.. option:: -help, --help
+
+Display available options
+
+.. option:: --help-hidden
+
+Display help for hidden options
+
+.. option:: --hip-link
+
+Link clang-offload-bundler bundles for HIP
+
+.. option:: -image\_base <arg>
+
+.. option:: -index-header-map
+
+Make the next included directory (-I or -F) an indexer header map
+
+.. option:: -init <arg>
+
+.. option:: -install\_name <arg>
+
+.. option:: -interface-stub-version=<arg>
+
+.. option:: -keep\_private\_externs
+
+.. option:: -lazy\_framework <arg>
+
+.. program:: clang1
+.. option:: -lazy\_library <arg>
+.. program:: clang
+
+.. option:: -mbig-endian, -EB
+
+.. option:: -mbranch-protection=<arg>
+
+Enforce targets of indirect branches and function returns
+
+.. option:: --migrate
+
+Run the migrator
+
+.. option:: -mios-simulator-version-min=<arg>, -miphonesimulator-version-min=<arg>
+
+.. option:: -mlinker-version=<arg>
+
+.. option:: -mlittle-endian, -EL
+
+.. option:: -mllvm <arg>
+
+Additional arguments to forward to LLVM's option processing
+
+.. option:: -module-dependency-dir <arg>
+
+Directory to dump module dependencies to
+
+.. option:: -mtvos-simulator-version-min=<arg>, -mappletvsimulator-version-min=<arg>
+
+.. option:: -multi\_module
+
+.. option:: -multiply\_defined <arg>
+
+.. program:: clang1
+.. option:: -multiply\_defined\_unused <arg>
+.. program:: clang
+
+.. option:: -mwatchos-simulator-version-min=<arg>, -mwatchsimulator-version-min=<arg>
+
+.. option:: --no-cuda-version-check
+
+Don't error out if the detected version of the CUDA install is too low for the requested CUDA gpu architecture.
+
+.. option:: -no-integrated-cpp, --no-integrated-cpp
+
+.. option:: -no\_dead\_strip\_inits\_and\_terms
+
+.. option:: -nobuiltininc
+
+Disable builtin #include directories
+
+.. option:: -nocudainc
+
+.. option:: -nocudalib
+
+.. option:: -nodefaultlibs
+
+.. option:: -nofixprebinding
+
+.. option:: -nolibc
+
+.. option:: -nomultidefs
+
+.. option:: -nopie, -no-pie
+
+.. option:: -noprebind
+
+.. option:: -noprofilelib
+
+.. option:: -noseglinkedit
+
+.. option:: -nostartfiles
+
+.. option:: -nostdinc, --no-standard-includes
+
+.. program:: clang1
+.. option:: -nostdinc++
+.. program:: clang
+
+Disable standard #include directories for the C++ standard library
+
+.. option:: -nostdlib, --no-standard-libraries
+
+.. program:: clang1
+.. option:: -nostdlib++
+.. program:: clang
+
+.. option:: -nostdlibinc
+
+.. option:: -o<file>, --output <arg>, --output=<arg>
+
+Write output to <file>
+
+.. option:: -objcmt-atomic-property
+
+Make migration to 'atomic' properties
+
+.. option:: -objcmt-migrate-all
+
+Enable migration to modern ObjC
+
+.. option:: -objcmt-migrate-annotation
+
+Enable migration to property and method annotations
+
+.. option:: -objcmt-migrate-designated-init
+
+Enable migration to infer NS\_DESIGNATED\_INITIALIZER for initializer methods
+
+.. option:: -objcmt-migrate-instancetype
+
+Enable migration to infer instancetype for method result type
+
+.. option:: -objcmt-migrate-literals
+
+Enable migration to modern ObjC literals
+
+.. option:: -objcmt-migrate-ns-macros
+
+Enable migration to NS\_ENUM/NS\_OPTIONS macros
+
+.. option:: -objcmt-migrate-property
+
+Enable migration to modern ObjC property
+
+.. option:: -objcmt-migrate-property-dot-syntax
+
+Enable migration of setter/getter messages to property-dot syntax
+
+.. option:: -objcmt-migrate-protocol-conformance
+
+Enable migration to add protocol conformance on classes
+
+.. option:: -objcmt-migrate-readonly-property
+
+Enable migration to modern ObjC readonly property
+
+.. option:: -objcmt-migrate-readwrite-property
+
+Enable migration to modern ObjC readwrite property
+
+.. option:: -objcmt-migrate-subscripting
+
+Enable migration to modern ObjC subscripting
+
+.. option:: -objcmt-ns-nonatomic-iosonly
+
+Enable migration to use NS\_NONATOMIC\_IOSONLY macro for setting property's 'atomic' attribute
+
+.. option:: -objcmt-returns-innerpointer-property
+
+Enable migration to annotate property with NS\_RETURNS\_INNER\_POINTER
+
+.. option:: -objcmt-whitelist-dir-path=<arg>, -objcmt-white-list-dir-path=<arg>
+
+Only modify files with a filename contained in the provided directory path
+
+.. option:: -object
+
+.. option:: -p, --profile
+
+.. option:: -pagezero\_size<arg>
+
+.. option:: -pg
+
+Enable mcount instrumentation
+
+.. option:: -pie
+
+.. option:: -pipe, --pipe
+
+Use pipes between commands, when possible
+
+.. option:: -prebind
+
+.. program:: clang1
+.. option:: -prebind\_all\_twolevel\_modules
+.. program:: clang
+
+.. option:: -preload
+
+.. option:: --print-diagnostic-categories
+
+.. option:: -print-effective-triple, --print-effective-triple
+
+Print the effective target triple
+
+.. option:: -print-file-name=<file>, --print-file-name=<file>, --print-file-name <arg>
+
+Print the full library path of <file>
+
+.. option:: -print-ivar-layout
+
+Enable Objective-C Ivar layout bitmap print trace
+
+.. option:: -print-libgcc-file-name, --print-libgcc-file-name
+
+Print the library path for the currently used compiler runtime library ("libgcc.a" or "libclang\_rt.builtins.\*.a")
+
+.. option:: -print-multi-directory, --print-multi-directory
+
+.. option:: -print-multi-lib, --print-multi-lib
+
+.. option:: -print-prog-name=<name>, --print-prog-name=<name>, --print-prog-name <arg>
+
+Print the full program path of <name>
+
+.. option:: -print-resource-dir, --print-resource-dir
+
+Print the resource directory pathname
+
+.. option:: -print-search-dirs, --print-search-dirs
+
+Print the paths used for finding libraries and programs
+
+.. option:: -print-target-triple, --print-target-triple
+
+Print the normalized target triple
+
+.. option:: -private\_bundle
+
+.. option:: -pthread, -no-pthread
+
+Support POSIX threads in generated code
+
+.. option:: -pthreads
+
+.. option:: -rdynamic
+
+.. option:: -read\_only\_relocs <arg>
+
+.. option:: -relocatable-pch, --relocatable-pch
+
+Whether to build a relocatable precompiled header
+
+.. option:: -remap
+
+.. option:: -rewrite-legacy-objc
+
+Rewrite Legacy Objective-C source to C++
+
+.. option:: -rtlib=<arg>, --rtlib=<arg>, --rtlib <arg>
+
+Compiler runtime library to use
+
+.. option:: -save-stats=<arg>, --save-stats=<arg>, -save-stats (equivalent to -save-stats=cwd), --save-stats (equivalent to -save-stats=cwd)
+
+Save llvm statistics.
+
+.. option:: -save-temps=<arg>, --save-temps=<arg>, -save-temps (equivalent to -save-temps=cwd), --save-temps (equivalent to -save-temps=cwd)
+
+Save intermediate compilation results.
+
+.. option:: -sectalign <arg1> <arg2> <arg3>
+
+.. option:: -sectcreate <arg1> <arg2> <arg3>
+
+.. option:: -sectobjectsymbols <arg1> <arg2>
+
+.. option:: -sectorder <arg1> <arg2> <arg3>
+
+.. option:: -seg1addr<arg>
+
+.. option:: -seg\_addr\_table <arg>
+
+.. program:: clang1
+.. option:: -seg\_addr\_table\_filename <arg>
+.. program:: clang
+
+.. option:: -segaddr <arg1> <arg2>
+
+.. option:: -segcreate <arg1> <arg2> <arg3>
+
+.. option:: -seglinkedit
+
+.. option:: -segprot <arg1> <arg2> <arg3>
+
+.. option:: -segs\_read\_<arg>
+
+.. program:: clang1
+.. option:: -segs\_read\_only\_addr <arg>
+.. program:: clang
+
+.. program:: clang2
+.. option:: -segs\_read\_write\_addr <arg>
+.. program:: clang
+
+.. option:: -serialize-diagnostics <arg>, --serialize-diagnostics <arg>
+
+Serialize compiler diagnostics to a file
+
+.. option:: -shared, --shared
+
+.. option:: -shared-libgcc
+
+.. option:: -shared-libsan, -shared-libasan
+
+Dynamically link the sanitizer runtime
+
+.. option:: -single\_module
+
+.. option:: -specs=<arg>, --specs=<arg>
+
+.. option:: -static, --static
+
+.. option:: -static-libgcc
+
+.. option:: -static-libsan
+
+Statically link the sanitizer runtime
+
+.. option:: -static-libstdc++
+
+.. option:: -static-pie
+
+.. option:: -std-default=<arg>
+
+.. option:: -stdlib=<arg>, --stdlib=<arg>, --stdlib <arg>
+
+C++ standard library to use
+
+.. option:: -sub\_library<arg>
+
+.. program:: clang1
+.. option:: -sub\_umbrella<arg>
+.. program:: clang
+
+.. option:: --sysroot=<arg>, --sysroot <arg>
+
+.. option:: --target-help
+
+.. option:: --target=<arg>, -target <arg>
+
+Generate code for the given target
+
+.. option:: -time
+
+Time individual commands
+
+.. option:: -traditional, --traditional
+
+.. option:: -traditional-cpp, --traditional-cpp
+
+Enable some traditional CPP emulation
+
+.. option:: -twolevel\_namespace
+
+.. program:: clang1
+.. option:: -twolevel\_namespace\_hints
+.. program:: clang
+
+.. option:: -umbrella <arg>
+
+.. option:: -unexported\_symbols\_list <arg>
+
+.. option:: -unwindlib=<arg>, --unwindlib=<arg>
+
+Unwind library to use
+
+.. option:: -v, --verbose
+
+Show commands to run and use verbose output
+
+.. option:: --verify-debug-info
+
+Verify the binary representation of debug output
+
+.. option:: --version
+
+Print version information
+
+.. option:: -w, --no-warnings
+
+Suppress all warnings
+
+.. option:: -weak-l<arg>
+
+.. option:: -weak\_framework <arg>
+
+.. program:: clang1
+.. option:: -weak\_library <arg>
+.. program:: clang
+
+.. program:: clang2
+.. option:: -weak\_reference\_mismatches <arg>
+.. program:: clang
+
+.. option:: -whatsloaded
+
+.. option:: -whyload
+
+.. option:: -working-directory<arg>, -working-directory=<arg>
+
+Resolve file paths relative to the specified directory
+
+.. option:: -x<language>, --language <arg>, --language=<arg>
+
+Treat subsequent input files as having type <language>
+
+.. option:: -y<arg>
+
+Actions
+=======
+The action to perform on the input.
+
+.. option:: -E, --preprocess
+
+Only run the preprocessor
+
+.. option:: -S, --assemble
+
+Only run preprocess and compilation steps
+
+.. option:: -c, --compile
+
+Only run preprocess, compile, and assemble steps
+
+.. option:: -emit-interface-stubs
+
+Generate Inteface Stub Files.
+
+.. option:: -emit-llvm
+
+Use the LLVM representation for assembler and object files
+
+.. option:: -fsyntax-only
+
+.. option:: -module-file-info
+
+Provide information about a particular module file
+
+.. option:: --precompile
+
+Only precompile the input
+
+.. option:: -rewrite-objc
+
+Rewrite Objective-C source to C++
+
+.. option:: -verify-pch
+
+Load and verify that a pre-compiled header file is not stale
+
+Compilation flags
+=================
+
+Flags controlling the behavior of Clang during compilation. These flags have
+no effect during actions that do not perform compilation.
+
+.. option:: -Xassembler <arg>
+
+Pass <arg> to the assembler
+
+.. option:: -Xclang <arg>
+
+Pass <arg> to the clang compiler
+
+.. option:: -fclang-abi-compat=<version>
+
+Attempt to match the ABI of Clang <version>
+
+.. option:: -fcomment-block-commands=<arg>,<arg2>...
+
+Treat each comma separated argument in <arg> as a documentation comment block command
+
+.. option:: -fcomplete-member-pointers, -fno-complete-member-pointers
+
+Require member pointer base types to be complete if they would be significant under the Microsoft ABI
+
+.. option:: -fcrash-diagnostics-dir=<arg>
+
+.. option:: -fdeclspec, -fno-declspec
+
+Allow \_\_declspec as a keyword
+
+.. option:: -fdepfile-entry=<arg>
+
+.. option:: -fdiagnostics-fixit-info, -fno-diagnostics-fixit-info
+
+.. option:: -fdiagnostics-format=<arg>
+
+.. option:: -fdiagnostics-parseable-fixits
+
+Print fix-its in machine parseable form
+
+.. option:: -fdiagnostics-print-source-range-info
+
+Print source range spans in numeric form
+
+.. option:: -fdiagnostics-show-category=<arg>
+
+.. option:: -fdiscard-value-names, -fno-discard-value-names
+
+Discard value names in LLVM IR
+
+.. option:: -fexperimental-isel, -fno-experimental-isel
+
+Enables the experimental global instruction selector
+
+.. option:: -fexperimental-new-pass-manager, -fno-experimental-new-pass-manager
+
+Enables an experimental new pass manager in LLVM.
+
+.. option:: -ffine-grained-bitfield-accesses, -fno-fine-grained-bitfield-accesses
+
+Use separate accesses for consecutive bitfield runs with legal widths and alignments.
+
+.. option:: -finline-functions, -fno-inline-functions
+
+Inline suitable functions
+
+.. option:: -finline-hint-functions
+
+Inline functions which are (explicitly or implicitly) marked inline
+
+.. option:: -fno-crash-diagnostics
+
+Disable auto-generation of preprocessed source files and a script for reproduction during a clang crash
+
+.. option:: -fno-sanitize-blacklist
+
+Don't use blacklist file for sanitizers
+
+.. option:: -fparse-all-comments
+
+.. option:: -frecord-command-line, -fno-record-command-line, -frecord-gcc-switches
+
+.. option:: -fsanitize-address-field-padding=<arg>
+
+Level of field padding for AddressSanitizer
+
+.. option:: -fsanitize-address-globals-dead-stripping
+
+Enable linker dead stripping of globals in AddressSanitizer
+
+.. option:: -fsanitize-address-poison-custom-array-cookie, -fno-sanitize-address-poison-custom-array-cookie
+
+Enable poisoning array cookies when using custom operator new\[\] in AddressSanitizer
+
+.. option:: -fsanitize-address-use-after-scope, -fno-sanitize-address-use-after-scope
+
+Enable use-after-scope detection in AddressSanitizer
+
+.. option:: -fsanitize-address-use-odr-indicator, -fno-sanitize-address-use-odr-indicator
+
+Enable ODR indicator globals to avoid false ODR violation reports in partially sanitized programs at the cost of an increase in binary size
+
+.. option:: -fsanitize-blacklist=<arg>
+
+Path to blacklist file for sanitizers
+
+.. option:: -fsanitize-cfi-cross-dso, -fno-sanitize-cfi-cross-dso
+
+Enable control flow integrity (CFI) checks for cross-DSO calls.
+
+.. option:: -fsanitize-cfi-icall-generalize-pointers
+
+Generalize pointers in CFI indirect call type signature checks
+
+.. option:: -fsanitize-coverage=<arg1>,<arg2>..., -fno-sanitize-coverage=<arg1>,<arg2>...
+
+Specify the type of coverage instrumentation for Sanitizers
+
+.. option:: -fsanitize-hwaddress-abi=<arg>
+
+Select the HWAddressSanitizer ABI to target (interceptor or platform, default interceptor)
+
+.. option:: -fsanitize-link-c++-runtime
+
+.. option:: -fsanitize-memory-track-origins, -fno-sanitize-memory-track-origins
+
+Enable origins tracking in MemorySanitizer
+
+.. program:: clang1
+.. option:: -fsanitize-memory-track-origins=<arg>
+.. program:: clang
+
+Enable origins tracking in MemorySanitizer
+
+.. option:: -fsanitize-memory-use-after-dtor, -fno-sanitize-memory-use-after-dtor
+
+Enable use-after-destroy detection in MemorySanitizer
+
+.. option:: -fsanitize-minimal-runtime, -fno-sanitize-minimal-runtime
+
+.. option:: -fsanitize-recover, -fno-sanitize-recover
+
+.. program:: clang1
+.. option:: -fsanitize-recover=<arg1>,<arg2>..., -fno-sanitize-recover=<arg1>,<arg2>...
+.. program:: clang
+
+Enable recovery for specified sanitizers
+
+.. option:: -fsanitize-stats, -fno-sanitize-stats
+
+Enable sanitizer statistics gathering.
+
+.. option:: -fsanitize-thread-atomics, -fno-sanitize-thread-atomics
+
+Enable atomic operations instrumentation in ThreadSanitizer (default)
+
+.. option:: -fsanitize-thread-func-entry-exit, -fno-sanitize-thread-func-entry-exit
+
+Enable function entry/exit instrumentation in ThreadSanitizer (default)
+
+.. option:: -fsanitize-thread-memory-access, -fno-sanitize-thread-memory-access
+
+Enable memory access instrumentation in ThreadSanitizer (default)
+
+.. option:: -fsanitize-trap=<arg1>,<arg2>..., -fno-sanitize-trap=<arg1>,<arg2>...
+
+Enable trapping for specified sanitizers
+
+.. option:: -fsanitize-undefined-strip-path-components=<number>
+
+Strip (or keep only, if negative) a given number of path components when emitting check metadata.
+
+.. option:: -fsanitize-undefined-trap-on-error, -fno-sanitize-undefined-trap-on-error
+
+.. option:: -fsanitize=<check>,<arg2>..., -fno-sanitize=<arg1>,<arg2>...
+
+Turn on runtime checks for various forms of undefined or suspicious behavior. See user manual for available checks
+
+.. option:: -moutline, -mno-outline
+
+Enable function outlining (AArch64 only)
+
+.. option:: --param <arg>, --param=<arg>
+
+.. option:: -print-supported-cpus, --print-supported-cpus, -mcpu=?, -mtune=?
+
+Print supported cpu models for the given target (if target is not specified, it will print the supported cpus for the default target)
+
+.. option:: -std=<arg>, --std=<arg>, --std <arg>
+
+Language standard to compile for
+
+Preprocessor flags
+~~~~~~~~~~~~~~~~~~
+
+Flags controlling the behavior of the Clang preprocessor.
+
+.. option:: -C, --comments
+
+Include comments in preprocessed output
+
+.. option:: -CC, --comments-in-macros
+
+Include comments from within macros in preprocessed output
+
+.. option:: -D<macro>=<value>, --define-macro <arg>, --define-macro=<arg>
+
+Define <macro> to <value> (or 1 if <value> omitted)
+
+.. option:: -H, --trace-includes
+
+Show header includes and nesting depth
+
+.. option:: -P, --no-line-commands
+
+Disable linemarker output in -E mode
+
+.. option:: -U<macro>, --undefine-macro <arg>, --undefine-macro=<arg>
+
+Undefine macro <macro>
+
+.. option:: -Wp,<arg>,<arg2>...
+
+Pass the comma separated arguments in <arg> to the preprocessor
+
+.. option:: -Xpreprocessor <arg>
+
+Pass <arg> to the preprocessor
+
+Include path management
+-----------------------
+
+Flags controlling how ``#include``\s are resolved to files.
+
+.. option:: -I<dir>, --include-directory <arg>, --include-directory=<arg>
+
+Add directory to include search path
+
+.. option:: -I-, --include-barrier
+
+Restrict all prior -I flags to double-quoted inclusion and remove current directory from include path
+
+.. option:: --cuda-path-ignore-env
+
+Ignore environment variables to detect CUDA installation
+
+.. option:: --cuda-path=<arg>
+
+CUDA installation path
+
+.. option:: -cxx-isystem<directory>
+
+Add directory to the C++ SYSTEM include search path
+
+.. option:: -fbuild-session-file=<file>
+
+Use the last modification time of <file> as the build session timestamp
+
+.. option:: -fbuild-session-timestamp=<time since Epoch in seconds>
+
+Time when the current build session started
+
+.. option:: -fmodule-file=\[<name>=\]<file>
+
+Specify the mapping of module name to precompiled module file, or load a module file if name is omitted.
+
+.. option:: -fmodules-cache-path=<directory>
+
+Specify the module cache path
+
+.. option:: -fmodules-disable-diagnostic-validation
+
+Disable validation of the diagnostic options when loading the module
+
+.. option:: -fmodules-prune-after=<seconds>
+
+Specify the interval (in seconds) after which a module file will be considered unused
+
+.. option:: -fmodules-prune-interval=<seconds>
+
+Specify the interval (in seconds) between attempts to prune the module cache
+
+.. option:: -fmodules-user-build-path <directory>
+
+Specify the module user build path
+
+.. option:: -fmodules-validate-once-per-build-session
+
+Don't verify input files for the modules if the module has been successfully validated or loaded during this build session
+
+.. option:: -fmodules-validate-system-headers, -fno-modules-validate-system-headers
+
+Validate the system headers that a module depends on when loading the module
+
+.. option:: -fprebuilt-module-path=<directory>
+
+Specify the prebuilt module path
+
+.. option:: -idirafter<arg>, --include-directory-after <arg>, --include-directory-after=<arg>
+
+Add directory to AFTER include search path
+
+.. option:: -iframework<arg>
+
+Add directory to SYSTEM framework search path
+
+.. option:: -iframeworkwithsysroot<directory>
+
+Add directory to SYSTEM framework search path, absolute paths are relative to -isysroot
+
+.. option:: -imacros<file>, --imacros<file>, --imacros=<arg>
+
+Include macros from file before parsing
+
+.. option:: -include<file>, --include<file>, --include=<arg>
+
+Include file before parsing
+
+.. option:: -include-pch <file>
+
+Include precompiled header file
+
+.. option:: -iprefix<dir>, --include-prefix <arg>, --include-prefix=<arg>
+
+Set the -iwithprefix/-iwithprefixbefore prefix
+
+.. option:: -iquote<directory>
+
+Add directory to QUOTE include search path
+
+.. option:: -isysroot<dir>
+
+Set the system root directory (usually /)
+
+.. option:: -isystem<directory>
+
+Add directory to SYSTEM include search path
+
+.. option:: -isystem-after<directory>
+
+Add directory to end of the SYSTEM include search path
+
+.. option:: -ivfsoverlay<arg>
+
+Overlay the virtual filesystem described by file over the real file system
+
+.. option:: -iwithprefix<dir>, --include-with-prefix <arg>, --include-with-prefix-after <arg>, --include-with-prefix-after=<arg>, --include-with-prefix=<arg>
+
+Set directory to SYSTEM include search path with prefix
+
+.. option:: -iwithprefixbefore<dir>, --include-with-prefix-before <arg>, --include-with-prefix-before=<arg>
+
+Set directory to include search path with prefix
+
+.. option:: -iwithsysroot<directory>
+
+Add directory to SYSTEM include search path, absolute paths are relative to -isysroot
+
+.. option:: --libomptarget-nvptx-path=<arg>
+
+Path to libomptarget-nvptx libraries
+
+.. option:: --ptxas-path=<arg>
+
+Path to ptxas (used for compiling CUDA code)
+
+.. option:: --system-header-prefix=<prefix>, --no-system-header-prefix=<prefix>, --system-header-prefix <arg>
+
+Treat all #include paths starting with <prefix> as including a system header.
+
+Dependency file generation
+--------------------------
+
+Flags controlling generation of a dependency file for ``make``-like build
+systems.
+
+.. option:: -M, --dependencies
+
+Like -MD, but also implies -E and writes to stdout by default
+
+.. option:: -MD, --write-dependencies
+
+Write a depfile containing user and system headers
+
+.. option:: -MF<file>
+
+Write depfile output from -MMD, -MD, -MM, or -M to <file>
+
+.. option:: -MG, --print-missing-file-dependencies
+
+Add missing headers to depfile
+
+.. option:: -MJ<arg>
+
+Write a compilation database entry per input
+
+.. option:: -MM, --user-dependencies
+
+Like -MMD, but also implies -E and writes to stdout by default
+
+.. option:: -MMD, --write-user-dependencies
+
+Write a depfile containing user headers
+
+.. option:: -MP
+
+Create phony target for each dependency (other than main file)
+
+.. option:: -MQ<arg>
+
+Specify name of main file output to quote in depfile
+
+.. option:: -MT<arg>
+
+Specify name of main file output in depfile
+
+.. option:: -MV
+
+Use NMake/Jom format for the depfile
+
+Dumping preprocessor state
+--------------------------
+
+Flags allowing the state of the preprocessor to be dumped in various ways.
+
+.. option:: -d
+
+.. program:: clang1
+.. option:: -d<arg>
+.. program:: clang
+
+.. option:: -dA
+
+.. option:: -dD
+
+Print macro definitions in -E mode in addition to normal output
+
+.. option:: -dI
+
+Print include directives in -E mode in addition to normal output
+
+.. option:: -dM
+
+Print macro definitions in -E mode instead of normal output
+
+Diagnostic flags
+~~~~~~~~~~~~~~~~
+
+Flags controlling which warnings, errors, and remarks Clang will generate.
+See the :doc:`full list of warning and remark flags <DiagnosticsReference>`.
+
+.. option:: -R<remark>
+
+Enable the specified remark
+
+.. option:: -Rpass-analysis=<arg>
+
+Report transformation analysis from optimization passes whose name matches the given POSIX regular expression
+
+.. option:: -Rpass-missed=<arg>
+
+Report missed transformations by optimization passes whose name matches the given POSIX regular expression
+
+.. option:: -Rpass=<arg>
+
+Report transformations performed by optimization passes whose name matches the given POSIX regular expression
+
+.. option:: -W<warning>, --extra-warnings, --warn-<arg>, --warn-=<arg>
+
+Enable the specified warning
+
+.. option:: -Wdeprecated, -Wno-deprecated
+
+Enable warnings for deprecated constructs and define \_\_DEPRECATED
+
+.. option:: -Wnonportable-cfstrings<arg>, -Wno-nonportable-cfstrings<arg>
+
+Target-independent compilation options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. option:: -Wframe-larger-than=<arg>
+
+.. option:: -fPIC, -fno-PIC
+
+.. option:: -fPIE, -fno-PIE
+
+.. option:: -faccess-control, -fno-access-control
+
+.. option:: -faddrsig, -fno-addrsig
+
+Emit an address-significance table
+
+.. option:: -falign-functions, -fno-align-functions
+
+.. program:: clang1
+.. option:: -falign-functions=<arg>
+.. program:: clang
+
+.. program:: clang1
+.. option:: -faligned-allocation, -faligned-new, -fno-aligned-allocation
+.. program:: clang
+
+Enable C++17 aligned allocation functions
+
+.. option:: -fallow-editor-placeholders, -fno-allow-editor-placeholders
+
+Treat editor placeholders as valid source code
+
+.. option:: -fallow-unsupported
+
+.. option:: -faltivec, -fno-altivec
+
+.. option:: -fansi-escape-codes
+
+Use ANSI escape codes for diagnostics
+
+.. option:: -fapple-kext, -findirect-virtual-calls, -fterminated-vtables
+
+Use Apple's kernel extensions ABI
+
+.. option:: -fapple-link-rtlib
+
+Force linking the clang builtins runtime library
+
+.. option:: -fapple-pragma-pack, -fno-apple-pragma-pack
+
+Enable Apple gcc-compatible #pragma pack handling
+
+.. option:: -fapplication-extension, -fno-application-extension
+
+Restrict code to those available for App Extensions
+
+.. option:: -fasm, -fno-asm
+
+.. option:: -fasm-blocks, -fno-asm-blocks
+
+.. option:: -fassociative-math, -fno-associative-math
+
+.. option:: -fassume-sane-operator-new, -fno-assume-sane-operator-new
+
+.. option:: -fast
+
+.. option:: -fastcp
+
+.. option:: -fastf
+
+.. option:: -fasynchronous-unwind-tables, -fno-asynchronous-unwind-tables
+
+.. option:: -fautolink, -fno-autolink
+
+.. option:: -fblocks, -fno-blocks
+
+Enable the 'blocks' language feature
+
+.. option:: -fbootclasspath=<arg>, --bootclasspath <arg>, --bootclasspath=<arg>
+
+.. option:: -fborland-extensions, -fno-borland-extensions
+
+Accept non-standard constructs supported by the Borland compiler
+
+.. option:: -fbracket-depth=<arg>
+
+.. option:: -fbuiltin, -fno-builtin
+
+.. option:: -fbuiltin-module-map
+
+Load the clang builtins module map file.
+
+.. option:: -fc++-static-destructors, -fno-c++-static-destructors
+
+Enable C++ static destructor registration (the default)
+
+.. option:: -fcaret-diagnostics, -fno-caret-diagnostics
+
+.. option:: -fcf-protection=<arg>, -fcf-protection (equivalent to -fcf-protection=full)
+
+Instrument control-flow architecture protection. Options: return, branch, full, none.
+
+.. option:: -fcf-runtime-abi=<arg>
+
+.. option:: -fchar8\_t, -fno-char8\_t
+
+Enable C++ builtin type char8\_t
+
+.. option:: -fclasspath=<arg>, --CLASSPATH <arg>, --CLASSPATH=<arg>, --classpath <arg>, --classpath=<arg>
+
+.. option:: -fcolor-diagnostics, -fno-color-diagnostics
+
+Use colors in diagnostics
+
+.. option:: -fcommon, -fno-common
+
+.. option:: -fcompile-resource=<arg>, --resource <arg>, --resource=<arg>
+
+.. option:: -fconstant-cfstrings, -fno-constant-cfstrings
+
+.. option:: -fconstant-string-class=<arg>
+
+.. option:: -fconstexpr-backtrace-limit=<arg>
+
+.. option:: -fconstexpr-depth=<arg>
+
+.. option:: -fconstexpr-steps=<arg>
+
+.. option:: -fcoroutines-ts, -fno-coroutines-ts
+
+Enable support for the C++ Coroutines TS
+
+.. option:: -fcoverage-mapping, -fno-coverage-mapping
+
+Generate coverage mapping to enable code coverage analysis
+
+.. option:: -fcreate-profile
+
+.. option:: -fcs-profile-generate
+
+Generate instrumented code to collect context sensitive execution counts into default.profraw (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. program:: clang1
+.. option:: -fcs-profile-generate=<directory>
+.. program:: clang
+
+Generate instrumented code to collect context sensitive execution counts into <directory>/default.profraw (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. option:: -fcxx-exceptions, -fno-cxx-exceptions
+
+Enable C++ exceptions
+
+.. option:: -fcxx-modules, -fno-cxx-modules
+
+.. option:: -fdata-sections, -fno-data-sections
+
+Place each data in its own section (ELF Only)
+
+.. option:: -fdebug-compilation-dir <arg>
+
+The compilation directory to embed in the debug info.
+
+.. option:: -fdebug-info-for-profiling, -fno-debug-info-for-profiling
+
+Emit extra debug info to make sample profile more accurate.
+
+.. option:: -fdebug-macro, -fno-debug-macro
+
+Emit macro debug information
+
+.. option:: -fdebug-pass-arguments
+
+.. option:: -fdebug-pass-structure
+
+.. option:: -fdebug-prefix-map=<arg>
+
+remap file source paths in debug info
+
+.. option:: -fdebug-ranges-base-address, -fno-debug-ranges-base-address
+
+Use DWARF base address selection entries in debug\_ranges
+
+.. option:: -fdebug-types-section, -fno-debug-types-section
+
+Place debug types in their own section (ELF Only)
+
+.. option:: -fdelayed-template-parsing, -fno-delayed-template-parsing
+
+Parse templated function definitions at the end of the translation unit
+
+.. option:: -fdelete-null-pointer-checks, -fno-delete-null-pointer-checks
+
+Treat usage of null pointers as undefined behavior.
+
+.. option:: -fdenormal-fp-math=<arg>
+
+.. option:: -fdiagnostics-absolute-paths
+
+Print absolute paths in diagnostics
+
+.. option:: -fdiagnostics-color, -fno-diagnostics-color
+
+.. program:: clang1
+.. option:: -fdiagnostics-color=<arg>
+.. program:: clang
+
+.. option:: -fdiagnostics-hotness-threshold=<number>
+
+Prevent optimization remarks from being output if they do not have at least this profile count
+
+.. option:: -fdiagnostics-show-hotness, -fno-diagnostics-show-hotness
+
+Enable profile hotness information in diagnostic line
+
+.. option:: -fdiagnostics-show-note-include-stack, -fno-diagnostics-show-note-include-stack
+
+Display include stacks for diagnostic notes
+
+.. option:: -fdiagnostics-show-option, -fno-diagnostics-show-option
+
+Print option name with mappable diagnostics
+
+.. option:: -fdiagnostics-show-template-tree
+
+Print a template comparison tree for differing templates
+
+.. option:: -fdigraphs, -fno-digraphs
+
+Enable alternative token representations '<:', ':>', '<%', '%>', '%:', '%:%:' (default)
+
+.. option:: -fdollars-in-identifiers, -fno-dollars-in-identifiers
+
+Allow '$' in identifiers
+
+.. option:: -fdouble-square-bracket-attributes, -fno-double-square-bracket-attributes
+
+Enable '\[\[\]\]' attributes in all C and C++ language modes
+
+.. option:: -fdwarf-directory-asm, -fno-dwarf-directory-asm
+
+.. option:: -fdwarf-exceptions
+
+Use DWARF style exceptions
+
+.. option:: -felide-constructors, -fno-elide-constructors
+
+.. option:: -feliminate-unused-debug-symbols, -fno-eliminate-unused-debug-symbols
+
+.. option:: -fembed-bitcode=<option>, -fembed-bitcode (equivalent to -fembed-bitcode=all), -fembed-bitcode-marker (equivalent to -fembed-bitcode=marker)
+
+Embed LLVM bitcode (option: off, all, bitcode, marker)
+
+.. option:: -femit-all-decls
+
+Emit all declarations, even if unused
+
+.. option:: -femulated-tls, -fno-emulated-tls
+
+Use emutls functions to access thread\_local variables
+
+.. option:: -fencoding=<arg>, --encoding <arg>, --encoding=<arg>
+
+.. option:: -ferror-limit=<arg>
+
+.. option:: -fescaping-block-tail-calls, -fno-escaping-block-tail-calls
+
+.. option:: -fexceptions, -fno-exceptions
+
+Enable support for exception handling
+
+.. option:: -fexec-charset=<arg>
+
+.. option:: -fextdirs=<arg>, --extdirs <arg>, --extdirs=<arg>
+
+.. option:: -ffast-math, -fno-fast-math
+
+Allow aggressive, lossy floating-point optimizations
+
+.. option:: -ffinite-math-only, -fno-finite-math-only
+
+.. option:: -ffixed-point, -fno-fixed-point
+
+Enable fixed point types
+
+.. option:: -ffor-scope, -fno-for-scope
+
+.. option:: -fforce-emit-vtables, -fno-force-emit-vtables
+
+Emits more virtual tables to improve devirtualization
+
+.. option:: -fforce-enable-int128, -fno-force-enable-int128
+
+Enable support for int128\_t type
+
+.. option:: -ffp-contract=<arg>
+
+Form fused FP ops (e.g. FMAs): fast (everywhere) \| on (according to FP\_CONTRACT pragma, default) \| off (never fuse)
+
+.. option:: -ffreestanding
+
+Assert that the compilation takes place in a freestanding environment
+
+.. option:: -ffunction-sections, -fno-function-sections
+
+Place each function in its own section (ELF Only)
+
+.. option:: -fgnu-inline-asm, -fno-gnu-inline-asm
+
+.. option:: -fgnu-keywords, -fno-gnu-keywords
+
+Allow GNU-extension keywords regardless of language standard
+
+.. option:: -fgnu-runtime
+
+Generate output compatible with the standard GNU Objective-C runtime
+
+.. option:: -fgnu89-inline, -fno-gnu89-inline
+
+Use the gnu89 inline semantics
+
+.. option:: -fhonor-infinities, -fhonor-infinites, -fno-honor-infinities
+
+.. option:: -fhonor-nans, -fno-honor-nans
+
+.. option:: -fhosted
+
+.. option:: -fimplicit-module-maps, -fmodule-maps, -fno-implicit-module-maps
+
+Implicitly search the file system for module map files.
+
+.. option:: -fimplicit-modules, -fno-implicit-modules
+
+.. option:: -finput-charset=<arg>
+
+.. option:: -finstrument-function-entry-bare
+
+Instrument function entry only, after inlining, without arguments to the instrumentation call
+
+.. option:: -finstrument-functions
+
+Generate calls to instrument function entry and exit
+
+.. option:: -finstrument-functions-after-inlining
+
+Like -finstrument-functions, but insert the calls after inlining
+
+.. option:: -fintegrated-as, -fno-integrated-as, -integrated-as
+
+Enable the integrated assembler
+
+.. option:: -fjump-tables, -fno-jump-tables
+
+.. option:: -fkeep-static-consts
+
+Keep static const variables even if unused
+
+.. option:: -flax-vector-conversions, -fno-lax-vector-conversions
+
+.. option:: -flimited-precision=<arg>
+
+.. option:: -flto, -fno-lto
+
+Enable LTO in 'full' mode
+
+.. option:: -flto-jobs=<arg>
+
+Controls the backend parallelism of -flto=thin (default of 0 means the number of threads will be derived from the number of CPUs detected)
+
+.. program:: clang1
+.. option:: -flto=<arg>
+.. program:: clang
+
+Set LTO mode to either 'full' or 'thin'
+
+.. option:: -fmacro-backtrace-limit=<arg>
+
+.. option:: -fmath-errno, -fno-math-errno
+
+Require math functions to indicate errors by setting errno
+
+.. option:: -fmax-type-align=<arg>
+
+Specify the maximum alignment to enforce on pointers lacking an explicit alignment
+
+.. option:: -fmerge-all-constants, -fno-merge-all-constants
+
+Allow merging of constants
+
+.. option:: -fmessage-length=<arg>
+
+.. option:: -fmodule-file-deps, -fno-module-file-deps
+
+.. option:: -fmodule-map-file=<file>
+
+Load this module map file
+
+.. option:: -fmodule-name=<name>, -fmodule-implementation-of <arg>, -fmodule-name <arg>
+
+Specify the name of the module to build
+
+.. option:: -fmodules, -fno-modules
+
+Enable the 'modules' language feature
+
+.. option:: -fmodules-decluse, -fno-modules-decluse
+
+Require declaration of modules used within a module
+
+.. option:: -fmodules-ignore-macro=<arg>
+
+Ignore the definition of the given macro when building and loading modules
+
+.. option:: -fmodules-search-all, -fno-modules-search-all
+
+Search even non-imported modules to resolve references
+
+.. option:: -fmodules-strict-decluse
+
+Like -fmodules-decluse but requires all headers to be in modules
+
+.. option:: -fmodules-ts
+
+Enable support for the C++ Modules TS
+
+.. option:: -fms-compatibility, -fno-ms-compatibility
+
+Enable full Microsoft Visual C++ compatibility
+
+.. option:: -fms-compatibility-version=<arg>
+
+Dot-separated value representing the Microsoft compiler version number to report in \_MSC\_VER (0 = don't define it (default))
+
+.. option:: -fms-extensions, -fno-ms-extensions
+
+Accept some non-standard constructs supported by the Microsoft compiler
+
+.. option:: -fms-memptr-rep=<arg>
+
+.. option:: -fms-volatile<arg>
+
+.. option:: -fmsc-version=<arg>
+
+Microsoft compiler version number to report in \_MSC\_VER (0 = don't define it (default))
+
+.. option:: -fmudflap
+
+.. option:: -fmudflapth
+
+.. option:: -fnested-functions
+
+.. option:: -fnew-alignment=<align>, -fnew-alignment <arg>
+
+Specifies the largest alignment guaranteed by '::operator new(size\_t)'
+
+.. option:: -fnext-runtime
+
+.. option:: -fno-builtin-<arg>
+
+Disable implicit builtin knowledge of a specific function
+
+.. option:: -fno-elide-type
+
+Do not elide types when printing diagnostics
+
+.. option:: -fno-max-type-align
+
+.. option:: -fno-operator-names
+
+Do not treat C++ operator name keywords as synonyms for operators
+
+.. option:: -fno-rtti-data
+
+Control emission of RTTI data
+
+.. option:: -fno-strict-modules-decluse
+
+.. option:: -fno-working-directory
+
+.. option:: -fnoxray-link-deps
+
+.. option:: -fobjc-abi-version=<arg>
+
+.. option:: -fobjc-arc, -fno-objc-arc
+
+Synthesize retain and release calls for Objective-C pointers
+
+.. option:: -fobjc-arc-exceptions, -fno-objc-arc-exceptions
+
+Use EH-safe code when synthesizing retains and releases in -fobjc-arc
+
+.. option:: -fobjc-convert-messages-to-runtime-calls, -fno-objc-convert-messages-to-runtime-calls
+
+.. option:: -fobjc-exceptions, -fno-objc-exceptions
+
+Enable Objective-C exceptions
+
+.. option:: -fobjc-infer-related-result-type, -fno-objc-infer-related-result-type
+
+.. option:: -fobjc-legacy-dispatch, -fno-objc-legacy-dispatch
+
+.. option:: -fobjc-link-runtime
+
+.. option:: -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi
+
+.. option:: -fobjc-nonfragile-abi-version=<arg>
+
+.. option:: -fobjc-runtime=<arg>
+
+Specify the target Objective-C runtime kind and version
+
+.. option:: -fobjc-sender-dependent-dispatch
+
+.. option:: -fobjc-weak, -fno-objc-weak
+
+Enable ARC-style weak references in Objective-C
+
+.. option:: -fomit-frame-pointer, -fno-omit-frame-pointer
+
+.. option:: -fopenmp, -fno-openmp
+
+Parse OpenMP pragmas and generate parallel code.
+
+.. option:: -fopenmp-simd, -fno-openmp-simd
+
+Emit OpenMP code only for SIMD-based constructs.
+
+.. option:: -fopenmp-version=<arg>
+
+.. program:: clang1
+.. option:: -fopenmp=<arg>
+.. program:: clang
+
+.. option:: -foperator-arrow-depth=<arg>
+
+.. option:: -foptimization-record-file=<arg>
+
+Specify the file name of any generated YAML optimization record
+
+.. option:: -foptimization-record-passes=<arg>
+
+Only include passes which match a specified regular expression in the generated optimization record (by default, include all passes)
+
+.. option:: -foptimize-sibling-calls, -fno-optimize-sibling-calls
+
+.. option:: -forder-file-instrumentation
+
+Generate instrumented code to collect order file into default.profraw file (overridden by '=' form of option or LLVM\_PROFILE\_FILE env var)
+
+.. option:: -foutput-class-dir=<arg>, --output-class-directory <arg>, --output-class-directory=<arg>
+
+.. option:: -fpack-struct, -fno-pack-struct
+
+.. program:: clang1
+.. option:: -fpack-struct=<arg>
+.. program:: clang
+
+Specify the default maximum struct packing alignment
+
+.. option:: -fpascal-strings, -fno-pascal-strings, -mpascal-strings
+
+Recognize and construct Pascal-style string literals
+
+.. option:: -fpass-plugin=<dsopath>
+
+Load pass plugin from a dynamic shared object file (only with new pass manager).
+
+.. option:: -fpcc-struct-return
+
+Override the default ABI to return all structs on the stack
+
+.. option:: -fpch-preprocess
+
+.. option:: -fpic, -fno-pic
+
+.. option:: -fpie, -fno-pie
+
+.. option:: -fplt, -fno-plt
+
+Use the PLT to make function calls
+
+.. option:: -fplugin=<dsopath>
+
+Load the named plugin (dynamic shared object)
+
+.. option:: -fpreserve-as-comments, -fno-preserve-as-comments
+
+.. option:: -fprofile-arcs, -fno-profile-arcs
+
+.. option:: -fprofile-dir=<arg>
+
+.. option:: -fprofile-exclude-files=<arg>
+
+Instrument only functions from files where names don't match all the regexes separated by a semi-colon
+
+.. option:: -fprofile-filter-files=<arg>
+
+Instrument only functions from files where names match any regex separated by a semi-colon
+
+.. option:: -fprofile-generate, -fno-profile-generate
+
+Generate instrumented code to collect execution counts into default.profraw (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. program:: clang1
+.. option:: -fprofile-generate=<directory>
+.. program:: clang
+
+Generate instrumented code to collect execution counts into <directory>/default.profraw (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. option:: -fprofile-instr-generate, -fno-profile-instr-generate
+
+Generate instrumented code to collect execution counts into default.profraw file (overridden by '=' form of option or LLVM\_PROFILE\_FILE env var)
+
+.. program:: clang1
+.. option:: -fprofile-instr-generate=<file>
+.. program:: clang
+
+Generate instrumented code to collect execution counts into <file> (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. option:: -fprofile-instr-use, -fno-profile-instr-use, -fprofile-use
+
+.. program:: clang1
+.. option:: -fprofile-instr-use=<arg>
+.. program:: clang
+
+Use instrumentation data for profile-guided optimization
+
+.. option:: -fprofile-remapping-file=<file>, -fprofile-remapping-file <arg>
+
+Use the remappings described in <file> to match the profile data against names in the program
+
+.. option:: -fprofile-sample-accurate, -fauto-profile-accurate, -fno-profile-sample-accurate
+
+Specifies that the sample profile is accurate. If the sample
+ profile is accurate, callsites without profile samples are marked
+ as cold. Otherwise, treat callsites without profile samples as if
+ we have no profile
+
+.. option:: -fprofile-sample-use, -fauto-profile, -fno-profile-sample-use
+
+.. program:: clang1
+.. option:: -fprofile-sample-use=<arg>, -fauto-profile=<arg>
+.. program:: clang
+
+Enable sample-based profile guided optimizations
+
+.. program:: clang1
+.. option:: -fprofile-use=<pathname>
+.. program:: clang
+
+Use instrumentation data for profile-guided optimization. If pathname is a directory, it reads from <pathname>/default.profdata. Otherwise, it reads from file <pathname>.
+
+.. option:: -freciprocal-math, -fno-reciprocal-math
+
+Allow division operations to be reassociated
+
+.. option:: -freg-struct-return
+
+Override the default ABI to return small structs in registers
+
+.. option:: -fregister-global-dtors-with-atexit, -fno-register-global-dtors-with-atexit
+
+Use atexit or \_\_cxa\_atexit to register global destructors
+
+.. option:: -frelaxed-template-template-args, -fno-relaxed-template-template-args
+
+Enable C++17 relaxed template template argument matching
+
+.. option:: -freroll-loops, -fno-reroll-loops
+
+Turn on loop reroller
+
+.. option:: -fretain-comments-from-system-headers
+
+.. option:: -frewrite-imports, -fno-rewrite-imports
+
+.. option:: -frewrite-includes, -fno-rewrite-includes
+
+.. option:: -frewrite-map-file <arg>
+
+.. program:: clang1
+.. option:: -frewrite-map-file=<arg>
+.. program:: clang
+
+.. option:: -fropi, -fno-ropi
+
+.. option:: -frtti, -fno-rtti
+
+.. option:: -frwpi, -fno-rwpi
+
+.. option:: -fsave-optimization-record, -fno-save-optimization-record
+
+Generate a YAML optimization record file
+
+.. program:: clang1
+.. option:: -fsave-optimization-record=<arg>
+.. program:: clang
+
+Generate an optimization record file in a specific format (default: YAML)
+
+.. option:: -fseh-exceptions
+
+Use SEH style exceptions
+
+.. option:: -fshort-enums, -fno-short-enums
+
+Allocate to an enum type only as many bytes as it needs for the declared range of possible values
+
+.. option:: -fshort-wchar, -fno-short-wchar
+
+Force wchar\_t to be a short unsigned int
+
+.. option:: -fshow-column, -fno-show-column
+
+.. option:: -fshow-overloads=<arg>
+
+Which overload candidates to show when overload resolution fails: best\|all; defaults to all
+
+.. option:: -fshow-source-location, -fno-show-source-location
+
+.. option:: -fsignaling-math, -fno-signaling-math
+
+.. option:: -fsigned-bitfields
+
+.. option:: -fsigned-char, -fno-signed-char, --signed-char
+
+.. option:: -fsigned-zeros, -fno-signed-zeros
+
+.. option:: -fsized-deallocation, -fno-sized-deallocation
+
+Enable C++14 sized global deallocation functions
+
+.. option:: -fsjlj-exceptions
+
+Use SjLj style exceptions
+
+.. option:: -fslp-vectorize, -fno-slp-vectorize, -ftree-slp-vectorize
+
+Enable the superword-level parallelism vectorization passes
+
+.. option:: -fspell-checking, -fno-spell-checking
+
+.. option:: -fspell-checking-limit=<arg>
+
+.. option:: -fsplit-dwarf-inlining, -fno-split-dwarf-inlining
+
+Provide minimal debug info in the object/executable to facilitate online symbolication/stack traces in the absence of .dwo/.dwp files when using Split DWARF
+
+.. option:: -fsplit-lto-unit, -fno-split-lto-unit
+
+Enables splitting of the LTO unit.
+
+.. option:: -fsplit-stack
+
+.. option:: -fstack-protector, -fno-stack-protector
+
+Enable stack protectors for some functions vulnerable to stack smashing. This uses a loose heuristic which considers functions vulnerable if they contain a char (or 8bit integer) array or constant sized calls to alloca, which are of greater size than ssp-buffer-size (default: 8 bytes). All variable sized calls to alloca are considered vulnerable
+
+.. option:: -fstack-protector-all
+
+Enable stack protectors for all functions
+
+.. option:: -fstack-protector-strong
+
+Enable stack protectors for some functions vulnerable to stack smashing. Compared to -fstack-protector, this uses a stronger heuristic that includes functions containing arrays of any size (and any type), as well as any calls to alloca or the taking of an address from a local variable
+
+.. option:: -fstack-size-section, -fno-stack-size-section
+
+Emit section containing metadata on function stack sizes
+
+.. option:: -fstandalone-debug, -fno-limit-debug-info, -fno-standalone-debug
+
+Emit full debug info for all types used by the program
+
+.. option:: -fstrict-aliasing, -fno-strict-aliasing
+
+.. option:: -fstrict-enums, -fno-strict-enums
+
+Enable optimizations based on the strict definition of an enum's value range
+
+.. option:: -fstrict-float-cast-overflow, -fno-strict-float-cast-overflow
+
+Assume that overflowing float-to-int casts are undefined (default)
+
+.. option:: -fstrict-overflow, -fno-strict-overflow
+
+.. option:: -fstrict-return, -fno-strict-return
+
+Always treat control flow paths that fall off the end of a non-void function as unreachable
+
+.. option:: -fstrict-vtable-pointers, -fno-strict-vtable-pointers
+
+Enable optimizations based on the strict rules for overwriting polymorphic C++ objects
+
+.. option:: -fstruct-path-tbaa, -fno-struct-path-tbaa
+
+.. option:: -fsymbol-partition=<arg>
+
+.. option:: -ftabstop=<arg>
+
+.. option:: -ftemplate-backtrace-limit=<arg>
+
+.. option:: -ftemplate-depth-<arg>
+
+.. option:: -ftemplate-depth=<arg>
+
+.. option:: -ftest-coverage
+
+.. option:: -fthinlto-index=<arg>
+
+Perform ThinLTO importing using provided function summary index
+
+.. option:: -fthreadsafe-statics, -fno-threadsafe-statics
+
+.. option:: -ftime-report
+
+.. option:: -ftime-trace
+
+.. option:: -ftls-model=<arg>
+
+.. option:: -ftrap-function=<arg>
+
+Issue call to specified function rather than a trap instruction
+
+.. option:: -ftrapping-math, -fno-trapping-math
+
+.. option:: -ftrapv
+
+Trap on integer overflow
+
+.. option:: -ftrapv-handler <arg>
+
+.. program:: clang1
+.. option:: -ftrapv-handler=<function name>
+.. program:: clang
+
+Specify the function to be called on overflow
+
+.. option:: -ftrigraphs, -fno-trigraphs, -trigraphs, --trigraphs
+
+Process trigraph sequences
+
+.. option:: -ftrivial-auto-var-init=<arg>
+
+Initialize trivial automatic stack variables: uninitialized (default) \| pattern
+
+.. option:: -funique-section-names, -fno-unique-section-names
+
+Use unique names for text and data sections (ELF Only)
+
+.. option:: -funit-at-a-time, -fno-unit-at-a-time
+
+.. option:: -funroll-loops, -fno-unroll-loops
+
+Turn on loop unroller
+
+.. option:: -funsafe-math-optimizations, -fno-unsafe-math-optimizations
+
+.. option:: -funsigned-bitfields
+
+.. option:: -funsigned-char, -fno-unsigned-char, --unsigned-char
+
+.. option:: -funwind-tables, -fno-unwind-tables
+
+.. option:: -fuse-cxa-atexit, -fno-use-cxa-atexit
+
+.. option:: -fuse-init-array, -fno-use-init-array
+
+Use .init\_array instead of .ctors
+
+.. option:: -fuse-ld=<arg>
+
+.. option:: -fuse-line-directives, -fno-use-line-directives
+
+.. option:: -fveclib=<arg>
+
+Use the given vector functions library
+
+.. option:: -fvectorize, -fno-vectorize, -ftree-vectorize
+
+Enable the loop vectorization passes
+
+.. option:: -fverbose-asm, -fno-verbose-asm
+
+.. option:: -fvisibility-global-new-delete-hidden
+
+Give global C++ operator new and delete declarations hidden visibility
+
+.. option:: -fvisibility-inlines-hidden
+
+Give inline C++ member functions hidden visibility by default
+
+.. option:: -fvisibility-ms-compat
+
+Give global types 'default' visibility and global functions and variables 'hidden' visibility by default
+
+.. option:: -fvisibility=<arg>
+
+Set the default symbol visibility for all global declarations
+
+.. option:: -fwhole-program-vtables, -fno-whole-program-vtables
+
+Enables whole-program vtable optimization. Requires -flto
+
+.. option:: -fwrapv, -fno-wrapv
+
+Treat signed integer overflow as two's complement
+
+.. option:: -fwritable-strings
+
+Store string literals as writable data
+
+.. option:: -fxray-always-emit-customevents, -fno-xray-always-emit-customevents
+
+Determine whether to always emit \_\_xray\_customevent(...) calls even if the function it appears in is not always instrumented.
+
+.. option:: -fxray-always-emit-typedevents, -fno-xray-always-emit-typedevents
+
+Determine whether to always emit \_\_xray\_typedevent(...) calls even if the function it appears in is not always instrumented.
+
+.. option:: -fxray-always-instrument=<arg>
+
+DEPRECATED: Filename defining the whitelist for imbuing the 'always instrument' XRay attribute.
+
+.. option:: -fxray-attr-list=<arg>
+
+Filename defining the list of functions/types for imbuing XRay attributes.
+
+.. option:: -fxray-instruction-threshold<arg>
+
+.. program:: clang1
+.. option:: -fxray-instruction-threshold=<arg>
+.. program:: clang
+
+Sets the minimum function size to instrument with XRay
+
+.. option:: -fxray-instrument, -fno-xray-instrument
+
+Generate XRay instrumentation sleds on function entry and exit
+
+.. option:: -fxray-instrumentation-bundle=<arg>
+
+Select which XRay instrumentation points to emit. Options: all, none, function, custom. Default is 'all'.
+
+.. option:: -fxray-link-deps
+
+Tells clang to add the link dependencies for XRay.
+
+.. option:: -fxray-modes=<arg>
+
+List of modes to link in by default into XRay instrumented binaries.
+
+.. option:: -fxray-never-instrument=<arg>
+
+DEPRECATED: Filename defining the whitelist for imbuing the 'never instrument' XRay attribute.
+
+.. option:: -fzero-initialized-in-bss, -fno-zero-initialized-in-bss
+
+.. option:: -fzvector, -fno-zvector, -mzvector
+
+Enable System z vector language extension
+
+.. option:: -mlong-double-128
+
+Force long double to be 128 bits
+
+.. option:: -mlong-double-64
+
+Force long double to be 64 bits
+
+.. option:: -pedantic, --pedantic, -no-pedantic, --no-pedantic
+
+.. option:: -pedantic-errors, --pedantic-errors
+
+OpenCL flags
+------------
+.. option:: -cl-denorms-are-zero
+
+OpenCL only. Allow denormals to be flushed to zero.
+
+.. option:: -cl-fast-relaxed-math
+
+OpenCL only. Sets -cl-finite-math-only and -cl-unsafe-math-optimizations, and defines \_\_FAST\_RELAXED\_MATH\_\_.
+
+.. option:: -cl-finite-math-only
+
+OpenCL only. Allow floating-point optimizations that assume arguments and results are not NaNs or +-Inf.
+
+.. option:: -cl-fp32-correctly-rounded-divide-sqrt
+
+OpenCL only. Specify that single precision floating-point divide and sqrt used in the program source are correctly rounded.
+
+.. option:: -cl-kernel-arg-info
+
+OpenCL only. Generate kernel argument metadata.
+
+.. option:: -cl-mad-enable
+
+OpenCL only. Allow use of less precise MAD computations in the generated binary.
+
+.. option:: -cl-no-signed-zeros
+
+OpenCL only. Allow use of less precise no signed zeros computations in the generated binary.
+
+.. option:: -cl-opt-disable
+
+OpenCL only. This option disables all optimizations. By default optimizations are enabled.
+
+.. option:: -cl-single-precision-constant
+
+OpenCL only. Treat double precision floating-point constant as single precision constant.
+
+.. option:: -cl-std=<arg>
+
+OpenCL language standard to compile for.
+
+.. option:: -cl-strict-aliasing
+
+OpenCL only. This option is added for compatibility with OpenCL 1.0.
+
+.. option:: -cl-uniform-work-group-size
+
+OpenCL only. Defines that the global work-size be a multiple of the work-group size specified to clEnqueueNDRangeKernel
+
+.. option:: -cl-unsafe-math-optimizations
+
+OpenCL only. Allow unsafe floating-point optimizations. Also implies -cl-no-signed-zeros and -cl-mad-enable.
+
+Target-dependent compilation options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. option:: -G<size>, -G=<arg>, -msmall-data-threshold=<arg>
+
+Put objects of at most <size> bytes into small data section (MIPS / Hexagon)
+
+.. option:: -m16
+
+.. option:: -m32
+
+.. option:: -m64
+
+.. option:: -mabi=<arg>
+
+.. option:: -malign-double
+
+Align doubles to two words in structs (x86 only)
+
+.. option:: -march=<arg>
+
+.. option:: -masm=<arg>
+
+.. option:: -mbackchain, -mno-backchain
+
+Link stack frames through backchain on System Z
+
+.. option:: -mcmodel=<arg>
+
+.. option:: -mconsole<arg>
+
+.. program:: clang1
+.. option:: -mcpu=<arg>, -mv5 (equivalent to -mcpu=hexagonv5), -mv55 (equivalent to -mcpu=hexagonv55), -mv60 (equivalent to -mcpu=hexagonv60), -mv62 (equivalent to -mcpu=hexagonv62), -mv65 (equivalent to -mcpu=hexagonv65), -mv66 (equivalent to -mcpu=hexagonv66)
+.. program:: clang
+
+.. option:: -mcrc, -mno-crc
+
+Allow use of CRC instructions (ARM/Mips only)
+
+.. option:: -mdefault-build-attributes<arg>, -mno-default-build-attributes<arg>
+
+.. option:: -mdll<arg>
+
+.. option:: -mdynamic-no-pic<arg>
+
+.. option:: -meabi <arg>
+
+Set EABI type, e.g. 4, 5 or gnu (default depends on triple)
+
+.. option:: -mfentry
+
+Insert calls to fentry at function entry (x86 only)
+
+.. option:: -mfloat-abi=<arg>
+
+.. option:: -mfpmath=<arg>
+
+.. option:: -mfpu=<arg>
+
+.. option:: -mglobal-merge, -mno-global-merge
+
+Enable merging of globals
+
+.. option:: -mhard-float
+
+.. option:: -mhwdiv=<arg>, --mhwdiv <arg>, --mhwdiv=<arg>
+
+.. option:: -mhwmult=<arg>
+
+.. option:: -miamcu, -mno-iamcu
+
+Use Intel MCU ABI
+
+.. option:: -mimplicit-float, -mno-implicit-float
+
+.. option:: -mimplicit-it=<arg>
+
+.. option:: -mincremental-linker-compatible, -mno-incremental-linker-compatible
+
+(integrated-as) Emit an object file which can be used with an incremental linker
+
+.. option:: -miphoneos-version-min=<arg>, -mios-version-min=<arg>
+
+.. option:: -mkernel
+
+.. option:: -mlong-calls, -mno-long-calls
+
+Generate branches with extended addressability, usually via indirect jumps.
+
+.. option:: -mmacosx-version-min=<arg>, -mmacos-version-min=<arg>
+
+Set Mac OS X deployment target
+
+.. option:: -mmcu=<arg>
+
+.. option:: -mms-bitfields, -mno-ms-bitfields
+
+Set the default structure layout to be compatible with the Microsoft compiler standard
+
+.. option:: -momit-leaf-frame-pointer, -mno-omit-leaf-frame-pointer
+
+Omit frame pointer setup for leaf functions
+
+.. option:: -moslib=<arg>
+
+.. option:: -mpie-copy-relocations, -mno-pie-copy-relocations
+
+Use copy relocations support for PIE builds
+
+.. option:: -mprefer-vector-width=<arg>
+
+Specifies preferred vector width for auto-vectorization. Defaults to 'none' which allows target specific decisions.
+
+.. option:: -mqdsp6-compat
+
+Enable hexagon-qdsp6 backward compatibility
+
+.. option:: -mrecip
+
+.. program:: clang1
+.. option:: -mrecip=<arg1>,<arg2>...
+.. program:: clang
+
+.. option:: -mred-zone, -mno-red-zone
+
+.. option:: -mregparm=<arg>
+
+.. option:: -mrelax-all, -mno-relax-all
+
+(integrated-as) Relax all machine instructions
+
+.. option:: -mretpoline, -mno-retpoline
+
+.. option:: -mrtd, -mno-rtd
+
+Make StdCall calling convention the default
+
+.. option:: -msign-return-address=<arg>
+
+Select return address signing scope
+
+.. option:: -msoft-float, -mno-soft-float
+
+Use software floating point
+
+.. option:: -mspeculative-load-hardening, -mno-speculative-load-hardening
+
+.. option:: -mstack-alignment=<arg>
+
+Set the stack alignment
+
+.. option:: -mstack-arg-probe, -mno-stack-arg-probe
+
+Enable stack probes
+
+.. option:: -mstack-probe-size=<arg>
+
+Set the stack probe size
+
+.. option:: -mstackrealign, -mno-stackrealign
+
+Force realign the stack at entry to every function
+
+.. option:: -mthread-model <arg>
+
+The thread model to use, e.g. posix, single (posix by default)
+
+.. option:: -mthreads<arg>
+
+.. option:: -mthumb, -mno-thumb
+
+.. option:: -mtls-direct-seg-refs, -mno-tls-direct-seg-refs
+
+Enable direct TLS access through segment registers (default)
+
+.. program:: clang1
+.. option:: -mtune=<arg>
+.. program:: clang
+
+.. option:: -mtvos-version-min=<arg>, -mappletvos-version-min=<arg>
+
+.. option:: -municode<arg>
+
+.. option:: -mvx, -mno-vx
+
+.. option:: -mwarn-nonportable-cfstrings, -mno-warn-nonportable-cfstrings
+
+.. option:: -mwatchos-version-min=<arg>
+
+.. option:: -mwavefrontsize64, -mno-wavefrontsize64
+
+Wavefront size 64 is used
+
+.. option:: -mwindows<arg>
+
+.. option:: -mx32
+
+AARCH64
+-------
+.. option:: -fcall-saved-x10
+
+Make the x10 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x11
+
+Make the x11 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x12
+
+Make the x12 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x13
+
+Make the x13 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x14
+
+Make the x14 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x15
+
+Make the x15 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x18
+
+Make the x18 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x8
+
+Make the x8 register call-saved (AArch64 only)
+
+.. option:: -fcall-saved-x9
+
+Make the x9 register call-saved (AArch64 only)
+
+.. option:: -ffixed-x1
+
+Reserve the 1 register (AArch64 only)
+
+.. option:: -ffixed-x10
+
+Reserve the 10 register (AArch64 only)
+
+.. option:: -ffixed-x11
+
+Reserve the 11 register (AArch64 only)
+
+.. option:: -ffixed-x12
+
+Reserve the 12 register (AArch64 only)
+
+.. option:: -ffixed-x13
+
+Reserve the 13 register (AArch64 only)
+
+.. option:: -ffixed-x14
+
+Reserve the 14 register (AArch64 only)
+
+.. option:: -ffixed-x15
+
+Reserve the 15 register (AArch64 only)
+
+.. option:: -ffixed-x18
+
+Reserve the 18 register (AArch64 only)
+
+.. option:: -ffixed-x2
+
+Reserve the 2 register (AArch64 only)
+
+.. option:: -ffixed-x20
+
+Reserve the 20 register (AArch64 only)
+
+.. option:: -ffixed-x21
+
+Reserve the 21 register (AArch64 only)
+
+.. option:: -ffixed-x22
+
+Reserve the 22 register (AArch64 only)
+
+.. option:: -ffixed-x23
+
+Reserve the 23 register (AArch64 only)
+
+.. option:: -ffixed-x24
+
+Reserve the 24 register (AArch64 only)
+
+.. option:: -ffixed-x25
+
+Reserve the 25 register (AArch64 only)
+
+.. option:: -ffixed-x26
+
+Reserve the 26 register (AArch64 only)
+
+.. option:: -ffixed-x27
+
+Reserve the 27 register (AArch64 only)
+
+.. option:: -ffixed-x28
+
+Reserve the 28 register (AArch64 only)
+
+.. option:: -ffixed-x3
+
+Reserve the 3 register (AArch64 only)
+
+.. option:: -ffixed-x4
+
+Reserve the 4 register (AArch64 only)
+
+.. option:: -ffixed-x5
+
+Reserve the 5 register (AArch64 only)
+
+.. option:: -ffixed-x6
+
+Reserve the 6 register (AArch64 only)
+
+.. option:: -ffixed-x7
+
+Reserve the 7 register (AArch64 only)
+
+.. option:: -ffixed-x9
+
+Reserve the 9 register (AArch64 only)
+
+.. option:: -mfix-cortex-a53-835769, -mno-fix-cortex-a53-835769
+
+Workaround Cortex-A53 erratum 835769 (AArch64 only)
+
+.. option:: -mgeneral-regs-only
+
+Generate code which only uses the general purpose registers (AArch64 only)
+
+AMDGPU
+------
+.. option:: -mcode-object-v3, -mno-code-object-v3
+
+Enable code object v3 (AMDGPU only)
+
+.. option:: -mcumode, -mno-cumode
+
+CU wavefront execution mode is used (AMDGPU only)
+
+.. option:: -msram-ecc, -mno-sram-ecc
+
+Enable SRAM ECC (AMDGPU only)
+
+.. option:: -mxnack, -mno-xnack
+
+Enable XNACK (AMDGPU only)
+
+ARM
+---
+.. option:: -ffixed-r9
+
+Reserve the r9 register (ARM only)
+
+.. option:: -mcmse
+
+Allow use of CMSE (Armv8-M Security Extensions)
+
+.. option:: -mexecute-only, -mno-execute-only, -mpure-code
+
+Disallow generation of data access to code sections (ARM only)
+
+.. option:: -mno-movt
+
+Disallow use of movt/movw pairs (ARM only)
+
+.. option:: -mno-neg-immediates
+
+Disallow converting instructions with negative immediates to their negation or inversion.
+
+.. option:: -mnocrc
+
+Disallow use of CRC instructions (ARM only)
+
+.. option:: -mrestrict-it, -mno-restrict-it
+
+Disallow generation of deprecated IT blocks for ARMv8. It is on by default for ARMv8 Thumb mode.
+
+.. option:: -mtp=<arg>
+
+Thread pointer access method (AArch32/AArch64 only)
+
+.. option:: -munaligned-access, -mno-unaligned-access
+
+Allow memory accesses to be unaligned (AArch32/AArch64 only)
+
+Hexagon
+-------
+.. option:: -mieee-rnd-near
+
+.. option:: -mmemops, -mno-memops
+
+Enable generation of memop instructions
+
+.. option:: -mnvj, -mno-nvj
+
+Enable generation of new-value jumps
+
+.. option:: -mnvs, -mno-nvs
+
+Enable generation of new-value stores
+
+.. option:: -mpackets, -mno-packets
+
+Enable generation of instruction packets
+
+Hexagon
+-------
+.. option:: -mhvx, -mno-hvx
+
+Enable Hexagon Vector eXtensions
+
+.. option:: -mhvx-length=<arg>
+
+Set Hexagon Vector Length
+
+.. program:: clang1
+.. option:: -mhvx=<arg>
+.. program:: clang
+
+Enable Hexagon Vector eXtensions
+
+MIPS
+----
+.. option:: -mabicalls, -mno-abicalls
+
+Enable SVR4-style position-independent code (Mips only)
+
+.. option:: -mabs=<arg>
+
+.. option:: -mcheck-zero-division, -mno-check-zero-division
+
+.. option:: -mcompact-branches=<arg>
+
+.. option:: -mdouble-float
+
+.. option:: -mdsp, -mno-dsp
+
+.. option:: -mdspr2, -mno-dspr2
+
+.. option:: -membedded-data, -mno-embedded-data
+
+Place constants in the .rodata section instead of the .sdata section even if they meet the -G <size> threshold (MIPS)
+
+.. option:: -mextern-sdata, -mno-extern-sdata
+
+Assume that externally defined data is in the small data if it meets the -G <size> threshold (MIPS)
+
+.. option:: -mfp32
+
+Use 32-bit floating point registers (MIPS only)
+
+.. option:: -mfp64
+
+Use 64-bit floating point registers (MIPS only)
+
+.. option:: -mginv, -mno-ginv
+
+.. option:: -mgpopt, -mno-gpopt
+
+Use GP relative accesses for symbols known to be in a small data section (MIPS)
+
+.. option:: -mindirect-jump=<arg>
+
+Change indirect jump instructions to inhibit speculation
+
+.. option:: -mips16
+
+.. option:: -mldc1-sdc1, -mno-ldc1-sdc1
+
+.. option:: -mlocal-sdata, -mno-local-sdata
+
+Extend the -G behaviour to object local data (MIPS)
+
+.. option:: -mmadd4, -mno-madd4
+
+Enable the generation of 4-operand madd.s, madd.d and related instructions.
+
+.. option:: -mmicromips, -mno-micromips
+
+.. option:: -mmsa, -mno-msa
+
+Enable MSA ASE (MIPS only)
+
+.. option:: -mmt, -mno-mt
+
+Enable MT ASE (MIPS only)
+
+.. option:: -mnan=<arg>
+
+.. option:: -mno-mips16
+
+.. option:: -msingle-float
+
+.. option:: -mvirt, -mno-virt
+
+.. option:: -mxgot, -mno-xgot
+
+PowerPC
+-------
+.. option:: -maltivec, -mno-altivec
+
+.. option:: -mcmpb, -mno-cmpb
+
+.. option:: -mcrbits, -mno-crbits
+
+.. option:: -mcrypto, -mno-crypto
+
+.. option:: -mdirect-move, -mno-direct-move
+
+.. option:: -mfloat128, -mno-float128
+
+.. option:: -mfprnd, -mno-fprnd
+
+.. option:: -mhtm, -mno-htm
+
+.. option:: -minvariant-function-descriptors, -mno-invariant-function-descriptors
+
+.. option:: -misel, -mno-isel
+
+.. option:: -mlongcall, -mno-longcall
+
+.. option:: -mmfocrf, -mmfcrf, -mno-mfocrf
+
+.. option:: -mpopcntd, -mno-popcntd
+
+.. option:: -mpower8-vector, -mno-power8-vector
+
+.. option:: -mpower9-vector, -mno-power9-vector
+
+.. option:: -mqpx, -mno-qpx
+
+.. option:: -msecure-plt
+
+.. option:: -mvsx, -mno-vsx
+
+WebAssembly
+-----------
+.. option:: -matomics, -mno-atomics
+
+.. option:: -mbulk-memory, -mno-bulk-memory
+
+.. option:: -mexception-handling, -mno-exception-handling
+
+.. option:: -mmultivalue, -mno-multivalue
+
+.. option:: -mmutable-globals, -mno-mutable-globals
+
+.. option:: -mnontrapping-fptoint, -mno-nontrapping-fptoint
+
+.. option:: -msign-ext, -mno-sign-ext
+
+.. option:: -msimd128, -mno-simd128
+
+.. option:: -mtail-call, -mno-tail-call
+
+.. option:: -munimplemented-simd128, -mno-unimplemented-simd128
+
+X86
+---
+.. option:: -m3dnow, -mno-3dnow
+
+.. option:: -m3dnowa, -mno-3dnowa
+
+.. option:: -madx, -mno-adx
+
+.. option:: -maes, -mno-aes
+
+.. option:: -mavx, -mno-avx
+
+.. option:: -mavx2, -mno-avx2
+
+.. option:: -mavx512bf16, -mno-avx512bf16
+
+.. option:: -mavx512bitalg, -mno-avx512bitalg
+
+.. option:: -mavx512bw, -mno-avx512bw
+
+.. option:: -mavx512cd, -mno-avx512cd
+
+.. option:: -mavx512dq, -mno-avx512dq
+
+.. option:: -mavx512er, -mno-avx512er
+
+.. option:: -mavx512f, -mno-avx512f
+
+.. option:: -mavx512ifma, -mno-avx512ifma
+
+.. option:: -mavx512pf, -mno-avx512pf
+
+.. option:: -mavx512vbmi, -mno-avx512vbmi
+
+.. option:: -mavx512vbmi2, -mno-avx512vbmi2
+
+.. option:: -mavx512vl, -mno-avx512vl
+
+.. option:: -mavx512vnni, -mno-avx512vnni
+
+.. option:: -mavx512vp2intersect, -mno-avx512vp2intersect
+
+.. option:: -mavx512vpopcntdq, -mno-avx512vpopcntdq
+
+.. option:: -mbmi, -mno-bmi
+
+.. option:: -mbmi2, -mno-bmi2
+
+.. option:: -mcldemote, -mno-cldemote
+
+.. option:: -mclflushopt, -mno-clflushopt
+
+.. option:: -mclwb, -mno-clwb
+
+.. option:: -mclzero, -mno-clzero
+
+.. option:: -mcx16, -mno-cx16
+
+.. option:: -menqcmd, -mno-enqcmd
+
+.. option:: -mf16c, -mno-f16c
+
+.. option:: -mfma, -mno-fma
+
+.. option:: -mfma4, -mno-fma4
+
+.. option:: -mfsgsbase, -mno-fsgsbase
+
+.. option:: -mfxsr, -mno-fxsr
+
+.. option:: -mgfni, -mno-gfni
+
+.. option:: -minvpcid, -mno-invpcid
+
+.. option:: -mlwp, -mno-lwp
+
+.. option:: -mlzcnt, -mno-lzcnt
+
+.. option:: -mmmx, -mno-mmx
+
+.. option:: -mmovbe, -mno-movbe
+
+.. option:: -mmovdir64b, -mno-movdir64b
+
+.. option:: -mmovdiri, -mno-movdiri
+
+.. option:: -mmpx, -mno-mpx
+
+.. option:: -mmwaitx, -mno-mwaitx
+
+.. option:: -mpclmul, -mno-pclmul
+
+.. option:: -mpconfig, -mno-pconfig
+
+.. option:: -mpku, -mno-pku
+
+.. option:: -mpopcnt, -mno-popcnt
+
+.. option:: -mprefetchwt1, -mno-prefetchwt1
+
+.. option:: -mprfchw, -mno-prfchw
+
+.. option:: -mptwrite, -mno-ptwrite
+
+.. option:: -mrdpid, -mno-rdpid
+
+.. option:: -mrdrnd, -mno-rdrnd
+
+.. option:: -mrdseed, -mno-rdseed
+
+.. option:: -mretpoline-external-thunk, -mno-retpoline-external-thunk
+
+.. option:: -mrtm, -mno-rtm
+
+.. option:: -msahf, -mno-sahf
+
+.. option:: -msgx, -mno-sgx
+
+.. option:: -msha, -mno-sha
+
+.. option:: -mshstk, -mno-shstk
+
+.. option:: -msse, -mno-sse
+
+.. option:: -msse2, -mno-sse2
+
+.. option:: -msse3, -mno-sse3
+
+.. option:: -msse4.1, -mno-sse4.1
+
+.. program:: clang1
+.. option:: -msse4.2, -mno-sse4.2, -msse4
+.. program:: clang
+
+.. option:: -msse4a, -mno-sse4a
+
+.. option:: -mssse3, -mno-ssse3
+
+.. option:: -mtbm, -mno-tbm
+
+.. option:: -mvaes, -mno-vaes
+
+.. option:: -mvpclmulqdq, -mno-vpclmulqdq
+
+.. option:: -mwaitpkg, -mno-waitpkg
+
+.. option:: -mwbnoinvd, -mno-wbnoinvd
+
+.. option:: -mx87, -m80387, -mno-x87
+
+.. option:: -mxop, -mno-xop
+
+.. option:: -mxsave, -mno-xsave
+
+.. option:: -mxsavec, -mno-xsavec
+
+.. option:: -mxsaveopt, -mno-xsaveopt
+
+.. option:: -mxsaves, -mno-xsaves
+
+RISCV
+-----
+.. option:: -mrelax, -mno-relax
+
+Enable linker relaxation
+
+.. option:: -msave-restore, -mno-save-restore
+
+Enable using library calls for save and restore
+
+Optimization level
+~~~~~~~~~~~~~~~~~~
+
+Flags controlling how much optimization should be performed.
+
+.. option:: -O<arg>, -O (equivalent to -O2), --optimize, --optimize=<arg>
+
+.. option:: -Ofast<arg>
+
+Debug information generation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Flags controlling how much and what kind of debug information should be
+generated.
+
+Kind and level of debug information
+-----------------------------------
+.. option:: -g, --debug, --debug=<arg>
+
+Generate source-level debug information
+
+.. option:: -gdwarf-2
+
+Generate source-level debug information with dwarf version 2
+
+.. option:: -gdwarf-3
+
+Generate source-level debug information with dwarf version 3
+
+.. option:: -gdwarf-4, -gdwarf
+
+Generate source-level debug information with dwarf version 4
+
+.. option:: -gdwarf-5
+
+Generate source-level debug information with dwarf version 5
+
+.. option:: -gfull
+
+.. option:: -gused
+
+Debug level
+___________
+.. option:: -g0
+
+.. option:: -g2
+
+.. option:: -g3
+
+.. option:: -ggdb0
+
+.. option:: -ggdb1
+
+.. option:: -ggdb2
+
+.. option:: -ggdb3
+
+.. option:: -gline-directives-only
+
+Emit debug line info directives only
+
+.. option:: -gline-tables-only, -g1, -gmlt
+
+Emit debug line number tables only
+
+.. option:: -gmodules
+
+Generate debug info with external references to clang modules or precompiled headers
+
+Debugger to tune debug information for
+______________________________________
+.. option:: -ggdb
+
+.. option:: -glldb
+
+.. option:: -gsce
+
+Debug information flags
+-----------------------
+.. option:: -gcolumn-info, -gno-column-info
+
+.. option:: -gdwarf-aranges
+
+.. option:: -gembed-source, -gno-embed-source
+
+Embed source text in DWARF debug sections
+
+.. option:: -ggnu-pubnames, -gno-gnu-pubnames
+
+.. option:: -gpubnames, -gno-pubnames
+
+.. option:: -grecord-command-line, -gno-record-command-line, -grecord-gcc-switches
+
+.. option:: -gsplit-dwarf
+
+.. program:: clang1
+.. option:: -gsplit-dwarf=<arg>
+.. program:: clang
+
+Set DWARF fission mode to either 'split' or 'single'
+
+.. option:: -gstrict-dwarf, -gno-strict-dwarf
+
+.. option:: -gz
+
+DWARF debug sections compression type
+
+.. program:: clang1
+.. option:: -gz=<arg>
+.. program:: clang
+
+DWARF debug sections compression type
+
+Static analyzer flags
+=====================
+
+Flags controlling the behavior of the Clang Static Analyzer.
+
+.. option:: -Xanalyzer <arg>
+
+Pass <arg> to the static analyzer
+
+Fortran compilation flags
+=========================
+
+Flags that will be passed onto the ``gfortran`` compiler when Clang is given
+a Fortran input.
+
+.. option:: -A<arg>, --assert <arg>, --assert=<arg>
+
+.. option:: -A-<arg>
+
+.. option:: -J<arg>
+
+.. option:: -cpp
+
+.. option:: -faggressive-function-elimination, -fno-aggressive-function-elimination
+
+.. option:: -falign-commons, -fno-align-commons
+
+.. option:: -fall-intrinsics, -fno-all-intrinsics
+
+.. option:: -fautomatic, -fno-automatic
+
+.. option:: -fbackslash, -fno-backslash
+
+.. option:: -fbacktrace, -fno-backtrace
+
+.. option:: -fblas-matmul-limit=<arg>
+
+.. option:: -fbounds-check, -fno-bounds-check
+
+.. option:: -fcheck-array-temporaries, -fno-check-array-temporaries
+
+.. option:: -fcheck=<arg>
+
+.. option:: -fcoarray=<arg>
+
+.. option:: -fconvert=<arg>
+
+.. option:: -fcray-pointer, -fno-cray-pointer
+
+.. option:: -fd-lines-as-code, -fno-d-lines-as-code
+
+.. option:: -fd-lines-as-comments, -fno-d-lines-as-comments
+
+.. option:: -fdefault-double-8, -fno-default-double-8
+
+.. option:: -fdefault-integer-8, -fno-default-integer-8
+
+.. option:: -fdefault-real-8, -fno-default-real-8
+
+.. option:: -fdollar-ok, -fno-dollar-ok
+
+.. option:: -fdump-fortran-optimized, -fno-dump-fortran-optimized
+
+.. option:: -fdump-fortran-original, -fno-dump-fortran-original
+
+.. option:: -fdump-parse-tree, -fno-dump-parse-tree
+
+.. option:: -fexternal-blas, -fno-external-blas
+
+.. option:: -ff2c, -fno-f2c
+
+.. option:: -ffixed-form, -fno-fixed-form
+
+.. option:: -ffixed-line-length-<arg>
+
+.. option:: -ffpe-trap=<arg>
+
+.. option:: -ffree-form, -fno-free-form
+
+.. option:: -ffree-line-length-<arg>
+
+.. option:: -ffrontend-optimize, -fno-frontend-optimize
+
+.. option:: -fimplicit-none, -fno-implicit-none
+
+.. option:: -finit-character=<arg>
+
+.. option:: -finit-integer=<arg>
+
+.. option:: -finit-local-zero, -fno-init-local-zero
+
+.. option:: -finit-logical=<arg>
+
+.. option:: -finit-real=<arg>
+
+.. option:: -finteger-4-integer-8, -fno-integer-4-integer-8
+
+.. option:: -fintrinsic-modules-path, -fno-intrinsic-modules-path
+
+.. option:: -fmax-array-constructor=<arg>
+
+.. option:: -fmax-errors=<arg>
+
+.. option:: -fmax-identifier-length, -fno-max-identifier-length
+
+.. option:: -fmax-stack-var-size=<arg>
+
+.. option:: -fmax-subrecord-length=<arg>
+
+.. option:: -fmodule-private, -fno-module-private
+
+.. option:: -fpack-derived, -fno-pack-derived
+
+.. option:: -fprotect-parens, -fno-protect-parens
+
+.. option:: -frange-check, -fno-range-check
+
+.. option:: -freal-4-real-10, -fno-real-4-real-10
+
+.. option:: -freal-4-real-16, -fno-real-4-real-16
+
+.. option:: -freal-4-real-8, -fno-real-4-real-8
+
+.. option:: -freal-8-real-10, -fno-real-8-real-10
+
+.. option:: -freal-8-real-16, -fno-real-8-real-16
+
+.. option:: -freal-8-real-4, -fno-real-8-real-4
+
+.. option:: -frealloc-lhs, -fno-realloc-lhs
+
+.. option:: -frecord-marker=<arg>
+
+.. option:: -frecursive, -fno-recursive
+
+.. option:: -frepack-arrays, -fno-repack-arrays
+
+.. option:: -fsecond-underscore, -fno-second-underscore
+
+.. option:: -fsign-zero, -fno-sign-zero
+
+.. option:: -fstack-arrays, -fno-stack-arrays
+
+.. option:: -funderscoring, -fno-underscoring
+
+.. option:: -fwhole-file, -fno-whole-file
+
+.. option:: -imultilib <arg>
+
+.. option:: -nocpp
+
+.. option:: -static-libgfortran
+
+Linker flags
+============
+Flags that are passed on to the linker
+
+.. option:: -L<dir>, --library-directory <arg>, --library-directory=<arg>
+
+Add directory to library search path
+
+.. option:: -Mach
+
+.. option:: -T<script>
+
+Specify <script> as linker script
+
+.. option:: -Tbss<addr>
+
+Set starting address of BSS to <addr>
+
+.. option:: -Tdata<addr>
+
+Set starting address of DATA to <addr>
+
+.. option:: -Ttext<addr>
+
+Set starting address of TEXT to <addr>
+
+.. option:: -Wl,<arg>,<arg2>...
+
+Pass the comma separated arguments in <arg> to the linker
+
+.. option:: -X
+
+.. option:: -Xlinker <arg>, --for-linker <arg>, --for-linker=<arg>
+
+Pass <arg> to the linker
+
+.. program:: clang1
+.. option:: -Z
+.. program:: clang
+
+.. option:: -e<arg>, --entry
+
+.. option:: -filelist <arg>
+
+.. option:: --hip-device-lib-path=<arg>
+
+HIP device library path
+
+.. option:: --hip-device-lib=<arg>
+
+HIP device library
+
+.. option:: -l<arg>
+
+.. option:: -r
+
+.. option:: -rpath <arg>
+
+.. option:: -s
+
+.. option:: -t
+
+.. option:: -u<arg>, --force-link <arg>, --force-link=<arg>
+
+.. option:: -undef
+
+undef all system defines
+
+.. option:: -undefined<arg>, --no-undefined
+
+.. option:: -z <arg>
+
+Pass -z <arg> to the linker
+
Added: www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangFormat.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangFormat.rst.txt?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangFormat.rst.txt (added)
+++ www-releases/trunk/9.0.0/tools/clang/docs/_sources/ClangFormat.rst.txt Thu Sep 19 07:32:46 2019
@@ -0,0 +1,229 @@
+===========
+ClangFormat
+===========
+
+`ClangFormat` describes a set of tools that are built on top of
+:doc:`LibFormat`. It can support your workflow in a variety of ways including a
+standalone tool and editor integrations.
+
+
+Standalone Tool
+===============
+
+:program:`clang-format` is located in `clang/tools/clang-format` and can be used
+to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code.
+
+.. code-block:: console
+
+ $ clang-format -help
+ OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code.
+
+ If no arguments are specified, it formats the code from standard input
+ and writes the result to the standard output.
+ If <file>s are given, it reformats the files. If -i is specified
+ together with <file>s, the files are edited in-place. Otherwise, the
+ result is written to the standard output.
+
+ USAGE: clang-format [options] [<file> ...]
+
+ OPTIONS:
+
+ Clang-format options:
+
+ -assume-filename=<string> - When reading from stdin, clang-format assumes this
+ filename to look for a style config file (with
+ -style=file) and to determine the language.
+ -cursor=<uint> - The position of the cursor when invoking
+ clang-format from an editor integration
+ -dump-config - Dump configuration options to stdout and exit.
+ Can be used with -style option.
+ -fallback-style=<string> - The name of the predefined style used as a
+ fallback in case clang-format is invoked with
+ -style=file, but can not find the .clang-format
+ file to use.
+ Use -fallback-style=none to skip formatting.
+ -i - Inplace edit <file>s, if specified.
+ -length=<uint> - Format a range of this length (in bytes).
+ Multiple ranges can be formatted by specifying
+ several -offset and -length pairs.
+ When only a single -offset is specified without
+ -length, clang-format will format up to the end
+ of the file.
+ Can only be used with one input file.
+ -lines=<string> - <start line>:<end line> - format a range of
+ lines (both 1-based).
+ Multiple ranges can be formatted by specifying
+ several -lines arguments.
+ Can't be used with -offset and -length.
+ Can only be used with one input file.
+ -offset=<uint> - Format a range starting at this byte offset.
+ Multiple ranges can be formatted by specifying
+ several -offset and -length pairs.
+ Can only be used with one input file.
+ -output-replacements-xml - Output replacements as XML.
+ -sort-includes - Sort touched include lines
+ -style=<string> - Coding style, currently supports:
+ LLVM, Google, Chromium, Mozilla, WebKit.
+ Use -style=file to load style configuration from
+ .clang-format file located in one of the parent
+ directories of the source file (or current
+ directory for stdin).
+ Use -style="{key: value, ...}" to set specific
+ parameters, e.g.:
+ -style="{BasedOnStyle: llvm, IndentWidth: 8}"
+ -verbose - If set, shows the list of processed files
+
+ Generic Options:
+
+ -help - Display available options (-help-hidden for more)
+ -help-list - Display list of available options (-help-list-hidden for more)
+ -version - Display the version of this program
+
+
+When the desired code formatting style is different from the available options,
+the style can be customized using the ``-style="{key: value, ...}"`` option or
+by putting your style configuration in the ``.clang-format`` or ``_clang-format``
+file in your project's directory and using ``clang-format -style=file``.
+
+An easy way to create the ``.clang-format`` file is:
+
+.. code-block:: console
+
+ clang-format -style=llvm -dump-config > .clang-format
+
+Available style options are described in :doc:`ClangFormatStyleOptions`.
+
+
+Vim Integration
+===============
+
+There is an integration for :program:`vim` which lets you run the
+:program:`clang-format` standalone tool on your current buffer, optionally
+selecting regions to reformat. The integration has the form of a `python`-file
+which can be found under `clang/tools/clang-format/clang-format.py`.
+
+This can be integrated by adding the following to your `.vimrc`:
+
+.. code-block:: vim
+
+ map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>
+ imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>
+
+The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the
+second line adds support for INSERT mode. Change "C-K" to another binding if
+you need :program:`clang-format` on a different key (C-K stands for Ctrl+k).
+
+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.
+
+It operates on the current, potentially unsaved buffer and does not create
+or save any files. To revert a formatting, just undo.
+
+An alternative option is to format changes when saving a file and thus to
+have a zero-effort integration into the coding workflow. To do this, add this to
+your `.vimrc`:
+
+.. code-block:: vim
+
+ function! Formatonsave()
+ let l:formatdiff = 1
+ pyf ~/llvm/tools/clang/tools/clang-format/clang-format.py
+ endfunction
+ autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave()
+
+
+Emacs Integration
+=================
+
+Similar to the integration for :program:`vim`, there is an integration for
+:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el`
+and used by adding this to your `.emacs`:
+
+.. code-block:: common-lisp
+
+ (load "<path-to-clang>/tools/clang-format/clang-format.el")
+ (global-set-key [C-M-tab] 'clang-format-region)
+
+This binds the function `clang-format-region` to C-M-tab, which then formats the
+current line or selected region.
+
+
+BBEdit Integration
+==================
+
+:program:`clang-format` 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
+`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in
+`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to
+point to your local copy of :program:`clang-format`.
+
+With this integration you can select the script from the Script menu and
+:program:`clang-format` 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.
+
+
+CLion Integration
+==================
+
+:program:`clang-format` is integrated into `CLion <https://www.jetbrains
+.com/clion/>`_ as an alternative code formatter. It is disabled by default and
+can be turned on in Settings/Preferences | Editor | Code Style.
+
+If :program:`clang-format` support is enabled, CLion detects config files when
+opening a project and suggests overriding the current IDE settings. Code style
+rules from the ``.clang-format`` files are then applied automatically to all
+editor actions, including auto-completion, code generation, and refactorings.
+
+
+Visual Studio Integration
+=========================
+
+Download the latest Visual Studio extension from the `alpha build site
+<https://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
+
+
+Script for patch reformatting
+=============================
+
+The python script `clang/tools/clang-format/clang-format-diff.py` parses the
+output of a unified diff and reformats all contained lines with
+:program:`clang-format`.
+
+.. code-block:: console
+
+ usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE]
+
+ Reformat changed lines in diff. Without -i option just output the diff that
+ would be introduced.
+
+ optional arguments:
+ -h, --help show this help message and exit
+ -i apply edits to files instead of displaying a diff
+ -p NUM strip the smallest prefix containing P slashes
+ -regex PATTERN custom pattern selecting file paths to reformat
+ -style STYLE formatting style to apply (LLVM, Google, Chromium, Mozilla,
+ WebKit)
+
+So to reformat all the lines in the latest :program:`git` commit, just do:
+
+.. code-block:: console
+
+ git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1
+
+With Mercurial/:program:`hg`:
+
+.. code-block:: console
+
+ hg diff -U0 --color=never | clang-format-diff.py -i -p1
+
+In an SVN client, you can do:
+
+.. code-block:: console
+
+ svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i
+
+The option `-U0` will create a diff without context lines (the script would format
+those as well).
More information about the llvm-commits
mailing list