[www-releases] r280493 - Add 3.9.0 source, docs and binaries

Hans Wennborg via llvm-commits llvm-commits at lists.llvm.org
Fri Sep 2 08:56:56 PDT 2016


Added: www-releases/trunk/3.9.0/tools/clang/docs/PCHInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/PCHInternals.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/PCHInternals.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/PCHInternals.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,590 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Precompiled Header and Modules Internals — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="ABI tags" href="ItaniumMangleAbiTags.html" />
+    <link rel="prev" title="Pretokenized Headers (PTH)" href="PTHInternals.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>Precompiled Header and Modules Internals</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ItaniumMangleAbiTags.html">ABI tags</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="precompiled-header-and-modules-internals">
+<h1>Precompiled Header and Modules Internals<a class="headerlink" href="#precompiled-header-and-modules-internals" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#using-precompiled-headers-with-clang" id="id1">Using Precompiled Headers with <tt class="docutils literal"><span class="pre">clang</span></tt></a></li>
+<li><a class="reference internal" href="#design-philosophy" id="id2">Design Philosophy</a></li>
+<li><a class="reference internal" href="#ast-file-contents" id="id3">AST File Contents</a><ul>
+<li><a class="reference internal" href="#metadata-block" id="id4">Metadata Block</a></li>
+<li><a class="reference internal" href="#source-manager-block" id="id5">Source Manager Block</a></li>
+<li><a class="reference internal" href="#preprocessor-block" id="id6">Preprocessor Block</a></li>
+<li><a class="reference internal" href="#types-block" id="id7">Types Block</a></li>
+<li><a class="reference internal" href="#declarations-block" id="id8">Declarations Block</a></li>
+<li><a class="reference internal" href="#statements-and-expressions" id="id9">Statements and Expressions</a></li>
+<li><a class="reference internal" href="#pchinternals-ident-table" id="id10">Identifier Table Block</a></li>
+<li><a class="reference internal" href="#method-pool-block" id="id11">Method Pool Block</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#ast-reader-integration-points" id="id12">AST Reader Integration Points</a></li>
+<li><a class="reference internal" href="#chained-precompiled-headers" id="id13">Chained precompiled headers</a></li>
+<li><a class="reference internal" href="#modules" id="id14">Modules</a></li>
+</ul>
+</div>
+<p>This document describes the design and implementation of Clang’s precompiled
+headers (PCH) and modules.  If you are interested in the end-user view, please
+see the <a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><em>User’s Manual</em></a>.</p>
+<div class="section" id="using-precompiled-headers-with-clang">
+<h2><a class="toc-backref" href="#id1">Using Precompiled Headers with <tt class="docutils literal"><span class="pre">clang</span></tt></a><a class="headerlink" href="#using-precompiled-headers-with-clang" title="Permalink to this headline">¶</a></h2>
+<p>The Clang compiler frontend, <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, supports two command line options
+for generating and using PCH files.</p>
+<p>To generate PCH files using <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, use the option <cite>-emit-pch</cite>:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>clang -cc1 test.h -emit-pch -o test.h.pch
+</pre></div>
+</div>
+<p>This option is transparently used by <tt class="docutils literal"><span class="pre">clang</span></tt> when generating PCH files.  The
+resulting PCH file contains the serialized form of the compiler’s internal
+representation after it has completed parsing and semantic analysis.  The PCH
+file can then be used as a prefix header with the <cite>-include-pch</cite>
+option:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>clang -cc1 -include-pch test.h.pch test.c -o test.s
+</pre></div>
+</div>
+</div>
+<div class="section" id="design-philosophy">
+<h2><a class="toc-backref" href="#id2">Design Philosophy</a><a class="headerlink" href="#design-philosophy" title="Permalink to this headline">¶</a></h2>
+<p>Precompiled headers are meant to improve overall compile times for projects, so
+the design of precompiled headers is entirely driven by performance concerns.
+The use case for precompiled headers is relatively simple: when there is a
+common set of headers that is included in nearly every source file in the
+project, we <em>precompile</em> that bundle of headers into a single precompiled
+header (PCH file).  Then, when compiling the source files in the project, we
+load the PCH file first (as a prefix header), which acts as a stand-in for that
+bundle of headers.</p>
+<p>A precompiled header implementation improves performance when:</p>
+<ul class="simple">
+<li>Loading the PCH file is significantly faster than re-parsing the bundle of
+headers stored within the PCH file.  Thus, a precompiled header design
+attempts to minimize the cost of reading the PCH file.  Ideally, this cost
+should not vary with the size of the precompiled header file.</li>
+<li>The cost of generating the PCH file initially is not so large that it
+counters the per-source-file performance improvement due to eliminating the
+need to parse the bundled headers in the first place.  This is particularly
+important on multi-core systems, because PCH file generation serializes the
+build when all compilations require the PCH file to be up-to-date.</li>
+</ul>
+<p>Modules, as implemented in Clang, use the same mechanisms as precompiled
+headers to save a serialized AST file (one per module) and use those AST
+modules.  From an implementation standpoint, modules are a generalization of
+precompiled headers, lifting a number of restrictions placed on precompiled
+headers.  In particular, there can only be one precompiled header and it must
+be included at the beginning of the translation unit.  The extensions to the
+AST file format required for modules are discussed in the section on
+<a class="reference internal" href="#pchinternals-modules"><em>modules</em></a>.</p>
+<p>Clang’s AST files are designed with a compact on-disk representation, which
+minimizes both creation time and the time required to initially load the AST
+file.  The AST file itself contains a serialized representation of Clang’s
+abstract syntax trees and supporting data structures, stored using the same
+compressed bitstream as <a class="reference external" href="http://llvm.org/docs/BitCodeFormat.html">LLVM’s bitcode file format</a>.</p>
+<p>Clang’s AST files are loaded “lazily” from disk.  When an AST file is initially
+loaded, Clang reads only a small amount of data from the AST file to establish
+where certain important data structures are stored.  The amount of data read in
+this initial load is independent of the size of the AST file, such that a
+larger AST file does not lead to longer AST load times.  The actual header data
+in the AST file — macros, functions, variables, types, etc. — is loaded
+only when it is referenced from the user’s code, at which point only that
+entity (and those entities it depends on) are deserialized from the AST file.
+With this approach, the cost of using an AST file for a translation unit is
+proportional to the amount of code actually used from the AST file, rather than
+being proportional to the size of the AST file itself.</p>
+<p>When given the <cite>-print-stats</cite> option, Clang produces statistics
+describing how much of the AST file was actually loaded from disk.  For a
+simple “Hello, World!” program that includes the Apple <tt class="docutils literal"><span class="pre">Cocoa.h</span></tt> header
+(which is built as a precompiled header), this option illustrates how little of
+the actual precompiled header is required:</p>
+<div class="highlight-none"><div class="highlight"><pre>*** AST File Statistics:
+  895/39981 source location entries read (2.238563%)
+  19/15315 types read (0.124061%)
+  20/82685 declarations read (0.024188%)
+  154/58070 identifiers read (0.265197%)
+  0/7260 selectors read (0.000000%)
+  0/30842 statements read (0.000000%)
+  4/8400 macros read (0.047619%)
+  1/4995 lexical declcontexts read (0.020020%)
+  0/4413 visible declcontexts read (0.000000%)
+  0/7230 method pool entries read (0.000000%)
+  0 method pool misses
+</pre></div>
+</div>
+<p>For this small program, only a tiny fraction of the source locations, types,
+declarations, identifiers, and macros were actually deserialized from the
+precompiled header.  These statistics can be useful to determine whether the
+AST file implementation can be improved by making more of the implementation
+lazy.</p>
+<p>Precompiled headers can be chained.  When you create a PCH while including an
+existing PCH, Clang can create the new PCH by referencing the original file and
+only writing the new data to the new file.  For example, you could create a PCH
+out of all the headers that are very commonly used throughout your project, and
+then create a PCH for every single source file in the project that includes the
+code that is specific to that file, so that recompiling the file itself is very
+fast, without duplicating the data from the common headers for every file.  The
+mechanisms behind chained precompiled headers are discussed in a <a class="reference internal" href="#pchinternals-chained"><em>later
+section</em></a>.</p>
+</div>
+<div class="section" id="ast-file-contents">
+<h2><a class="toc-backref" href="#id3">AST File Contents</a><a class="headerlink" href="#ast-file-contents" title="Permalink to this headline">¶</a></h2>
+<p>An AST file produced by clang is an object file container with a <tt class="docutils literal"><span class="pre">clangast</span></tt>
+(COFF) or <tt class="docutils literal"><span class="pre">__clangast</span></tt> (ELF and Mach-O) section containing the serialized AST.
+Other target-specific sections in the object file container are used to hold
+debug information for the data types defined in the AST.  Tools built on top of
+libclang that do not need debug information may also produce raw AST files that
+only contain the serialized AST.</p>
+<p>The <tt class="docutils literal"><span class="pre">clangast</span></tt> section is organized into several different blocks, each of
+which contains the serialized representation of a part of Clang’s internal
+representation.  Each of the blocks corresponds to either a block or a record
+within <a class="reference external" href="http://llvm.org/docs/BitCodeFormat.html">LLVM’s bitstream format</a>.
+The contents of each of these logical blocks are described below.</p>
+<img alt="_images/PCHLayout.png" src="_images/PCHLayout.png" />
+<p>The <tt class="docutils literal"><span class="pre">llvm-objdump</span></tt> utility provides a <tt class="docutils literal"><span class="pre">-raw-clang-ast</span></tt> option to extract the
+binary contents of the AST section from an object file container.</p>
+<p>The <a class="reference external" href="http://llvm.org/docs/CommandGuide/llvm-bcanalyzer.html">llvm-bcanalyzer</a>
+utility can be used to examine the actual structure of the bitstream for the AST
+section.  This information can be used both to help understand the structure of
+the AST section and to isolate areas where the AST representation can still be
+optimized, e.g., through the introduction of abbreviations.</p>
+<div class="section" id="metadata-block">
+<h3><a class="toc-backref" href="#id4">Metadata Block</a><a class="headerlink" href="#metadata-block" title="Permalink to this headline">¶</a></h3>
+<p>The metadata block contains several records that provide information about how
+the AST file was built.  This metadata is primarily used to validate the use of
+an AST file.  For example, a precompiled header built for a 32-bit x86 target
+cannot be used when compiling for a 64-bit x86 target.  The metadata block
+contains information about:</p>
+<dl class="docutils">
+<dt>Language options</dt>
+<dd>Describes the particular language dialect used to compile the AST file,
+including major options (e.g., Objective-C support) and more minor options
+(e.g., support for “<tt class="docutils literal"><span class="pre">//</span></tt>” comments).  The contents of this record correspond to
+the <tt class="docutils literal"><span class="pre">LangOptions</span></tt> class.</dd>
+<dt>Target architecture</dt>
+<dd>The target triple that describes the architecture, platform, and ABI for
+which the AST file was generated, e.g., <tt class="docutils literal"><span class="pre">i386-apple-darwin9</span></tt>.</dd>
+<dt>AST version</dt>
+<dd>The major and minor version numbers of the AST file format.  Changes in the
+minor version number should not affect backward compatibility, while changes
+in the major version number imply that a newer compiler cannot read an older
+precompiled header (and vice-versa).</dd>
+<dt>Original file name</dt>
+<dd>The full path of the header that was used to generate the AST file.</dd>
+<dt>Predefines buffer</dt>
+<dd>Although not explicitly stored as part of the metadata, the predefines buffer
+is used in the validation of the AST file.  The predefines buffer itself
+contains code generated by the compiler to initialize the preprocessor state
+according to the current target, platform, and command-line options.  For
+example, the predefines buffer will contain “<tt class="docutils literal"><span class="pre">#define</span> <span class="pre">__STDC__</span> <span class="pre">1</span></tt>” when we
+are compiling C without Microsoft extensions.  The predefines buffer itself
+is stored within the <a class="reference internal" href="#pchinternals-sourcemgr"><em>Source Manager Block</em></a>, but its contents are
+verified along with the rest of the metadata.</dd>
+</dl>
+<p>A chained PCH file (that is, one that references another PCH) and a module
+(which may import other modules) have additional metadata containing the list
+of all AST files that this AST file depends on.  Each of those files will be
+loaded along with this AST file.</p>
+<p>For chained precompiled headers, the language options, target architecture and
+predefines buffer data is taken from the end of the chain, since they have to
+match anyway.</p>
+</div>
+<div class="section" id="source-manager-block">
+<span id="pchinternals-sourcemgr"></span><h3><a class="toc-backref" href="#id5">Source Manager Block</a><a class="headerlink" href="#source-manager-block" title="Permalink to this headline">¶</a></h3>
+<p>The source manager block contains the serialized representation of Clang’s
+<a class="reference internal" href="InternalsManual.html#sourcemanager"><em>SourceManager</em></a> class, which handles the mapping from
+source locations (as represented in Clang’s abstract syntax tree) into actual
+column/line positions within a source file or macro instantiation.  The AST
+file’s representation of the source manager also includes information about all
+of the headers that were (transitively) included when building the AST file.</p>
+<p>The bulk of the source manager block is dedicated to information about the
+various files, buffers, and macro instantiations into which a source location
+can refer.  Each of these is referenced by a numeric “file ID”, which is a
+unique number (allocated starting at 1) stored in the source location.  Clang
+serializes the information for each kind of file ID, along with an index that
+maps file IDs to the position within the AST file where the information about
+that file ID is stored.  The data associated with a file ID is loaded only when
+required by the front end, e.g., to emit a diagnostic that includes a macro
+instantiation history inside the header itself.</p>
+<p>The source manager block also contains information about all of the headers
+that were included when building the AST file.  This includes information about
+the controlling macro for the header (e.g., when the preprocessor identified
+that the contents of the header dependent on a macro like
+<tt class="docutils literal"><span class="pre">LLVM_CLANG_SOURCEMANAGER_H</span></tt>).</p>
+</div>
+<div class="section" id="preprocessor-block">
+<span id="pchinternals-preprocessor"></span><h3><a class="toc-backref" href="#id6">Preprocessor Block</a><a class="headerlink" href="#preprocessor-block" title="Permalink to this headline">¶</a></h3>
+<p>The preprocessor block contains the serialized representation of the
+preprocessor.  Specifically, it contains all of the macros that have been
+defined by the end of the header used to build the AST file, along with the
+token sequences that comprise each macro.  The macro definitions are only read
+from the AST file when the name of the macro first occurs in the program.  This
+lazy loading of macro definitions is triggered by lookups into the
+<a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>.</p>
+</div>
+<div class="section" id="types-block">
+<span id="pchinternals-types"></span><h3><a class="toc-backref" href="#id7">Types Block</a><a class="headerlink" href="#types-block" title="Permalink to this headline">¶</a></h3>
+<p>The types block contains the serialized representation of all of the types
+referenced in the translation unit.  Each Clang type node (<tt class="docutils literal"><span class="pre">PointerType</span></tt>,
+<tt class="docutils literal"><span class="pre">FunctionProtoType</span></tt>, etc.) has a corresponding record type in the AST file.
+When types are deserialized from the AST file, the data within the record is
+used to reconstruct the appropriate type node using the AST context.</p>
+<p>Each type has a unique type ID, which is an integer that uniquely identifies
+that type.  Type ID 0 represents the NULL type, type IDs less than
+<tt class="docutils literal"><span class="pre">NUM_PREDEF_TYPE_IDS</span></tt> represent predefined types (<tt class="docutils literal"><span class="pre">void</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, etc.),
+while other “user-defined” type IDs are assigned consecutively from
+<tt class="docutils literal"><span class="pre">NUM_PREDEF_TYPE_IDS</span></tt> upward as the types are encountered.  The AST file has
+an associated mapping from the user-defined types block to the location within
+the types block where the serialized representation of that type resides,
+enabling lazy deserialization of types.  When a type is referenced from within
+the AST file, that reference is encoded using the type ID shifted left by 3
+bits.  The lower three bits are used to represent the <tt class="docutils literal"><span class="pre">const</span></tt>, <tt class="docutils literal"><span class="pre">volatile</span></tt>,
+and <tt class="docutils literal"><span class="pre">restrict</span></tt> qualifiers, as in Clang’s <a class="reference internal" href="InternalsManual.html#qualtype"><em>QualType</em></a> class.</p>
+</div>
+<div class="section" id="declarations-block">
+<span id="pchinternals-decls"></span><h3><a class="toc-backref" href="#id8">Declarations Block</a><a class="headerlink" href="#declarations-block" title="Permalink to this headline">¶</a></h3>
+<p>The declarations block contains the serialized representation of all of the
+declarations referenced in the translation unit.  Each Clang declaration node
+(<tt class="docutils literal"><span class="pre">VarDecl</span></tt>, <tt class="docutils literal"><span class="pre">FunctionDecl</span></tt>, etc.) has a corresponding record type in the
+AST file.  When declarations are deserialized from the AST file, the data
+within the record is used to build and populate a new instance of the
+corresponding <tt class="docutils literal"><span class="pre">Decl</span></tt> node.  As with types, each declaration node has a
+numeric ID that is used to refer to that declaration within the AST file.  In
+addition, a lookup table provides a mapping from that numeric ID to the offset
+within the precompiled header where that declaration is described.</p>
+<p>Declarations in Clang’s abstract syntax trees are stored hierarchically.  At
+the top of the hierarchy is the translation unit (<tt class="docutils literal"><span class="pre">TranslationUnitDecl</span></tt>),
+which contains all of the declarations in the translation unit but is not
+actually written as a specific declaration node.  Its child declarations (such
+as functions or struct types) may also contain other declarations inside them,
+and so on.  Within Clang, each declaration is stored within a <a class="reference internal" href="InternalsManual.html#declcontext"><em>declaration
+context</em></a>, as represented by the <tt class="docutils literal"><span class="pre">DeclContext</span></tt> class.
+Declaration contexts provide the mechanism to perform name lookup within a
+given declaration (e.g., find the member named <tt class="docutils literal"><span class="pre">x</span></tt> in a structure) and
+iterate over the declarations stored within a context (e.g., iterate over all
+of the fields of a structure for structure layout).</p>
+<p>In Clang’s AST file format, deserializing a declaration that is a
+<tt class="docutils literal"><span class="pre">DeclContext</span></tt> is a separate operation from deserializing all of the
+declarations stored within that declaration context.  Therefore, Clang will
+deserialize the translation unit declaration without deserializing the
+declarations within that translation unit.  When required, the declarations
+stored within a declaration context will be deserialized.  There are two
+representations of the declarations within a declaration context, which
+correspond to the name-lookup and iteration behavior described above:</p>
+<ul class="simple">
+<li>When the front end performs name lookup to find a name <tt class="docutils literal"><span class="pre">x</span></tt> within a given
+declaration context (for example, during semantic analysis of the expression
+<tt class="docutils literal"><span class="pre">p->x</span></tt>, where <tt class="docutils literal"><span class="pre">p</span></tt>‘s type is defined in the precompiled header), Clang
+refers to an on-disk hash table that maps from the names within that
+declaration context to the declaration IDs that represent each visible
+declaration with that name.  The actual declarations will then be
+deserialized to provide the results of name lookup.</li>
+<li>When the front end performs iteration over all of the declarations within a
+declaration context, all of those declarations are immediately
+de-serialized.  For large declaration contexts (e.g., the translation unit),
+this operation is expensive; however, large declaration contexts are not
+traversed in normal compilation, since such a traversal is unnecessary.
+However, it is common for the code generator and semantic analysis to
+traverse declaration contexts for structs, classes, unions, and
+enumerations, although those contexts contain relatively few declarations in
+the common case.</li>
+</ul>
+</div>
+<div class="section" id="statements-and-expressions">
+<h3><a class="toc-backref" href="#id9">Statements and Expressions</a><a class="headerlink" href="#statements-and-expressions" title="Permalink to this headline">¶</a></h3>
+<p>Statements and expressions are stored in the AST file in both the <a class="reference internal" href="#pchinternals-types"><em>types</em></a> and the <a class="reference internal" href="#pchinternals-decls"><em>declarations</em></a> blocks,
+because every statement or expression will be associated with either a type or
+declaration.  The actual statement and expression records are stored
+immediately following the declaration or type that owns the statement or
+expression.  For example, the statement representing the body of a function
+will be stored directly following the declaration of the function.</p>
+<p>As with types and declarations, each statement and expression kind in Clang’s
+abstract syntax tree (<tt class="docutils literal"><span class="pre">ForStmt</span></tt>, <tt class="docutils literal"><span class="pre">CallExpr</span></tt>, etc.) has a corresponding
+record type in the AST file, which contains the serialized representation of
+that statement or expression.  Each substatement or subexpression within an
+expression is stored as a separate record (which keeps most records to a fixed
+size).  Within the AST file, the subexpressions of an expression are stored, in
+reverse order, prior to the expression that owns those expression, using a form
+of <a class="reference external" href="http://en.wikipedia.org/wiki/Reverse_Polish_notation">Reverse Polish Notation</a>.  For example, an
+expression <tt class="docutils literal"><span class="pre">3</span> <span class="pre">-</span> <span class="pre">4</span> <span class="pre">+</span> <span class="pre">5</span></tt> would be represented as follows:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="100%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(5)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(4)</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(3)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(-)</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">IntegerLiteral(+)</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">STOP</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p>When reading this representation, Clang evaluates each expression record it
+encounters, builds the appropriate abstract syntax tree node, and then pushes
+that expression on to a stack.  When a record contains <em>N</em> subexpressions —
+<tt class="docutils literal"><span class="pre">BinaryOperator</span></tt> has two of them — those expressions are popped from the
+top of the stack.  The special STOP code indicates that we have reached the end
+of a serialized expression or statement; other expression or statement records
+may follow, but they are part of a different expression.</p>
+</div>
+<div class="section" id="pchinternals-ident-table">
+<span id="identifier-table-block"></span><h3><a class="toc-backref" href="#id10">Identifier Table Block</a><a class="headerlink" href="#pchinternals-ident-table" title="Permalink to this headline">¶</a></h3>
+<p>The identifier table block contains an on-disk hash table that maps each
+identifier mentioned within the AST file to the serialized representation of
+the identifier’s information (e.g, the <tt class="docutils literal"><span class="pre">IdentifierInfo</span></tt> structure).  The
+serialized representation contains:</p>
+<ul class="simple">
+<li>The actual identifier string.</li>
+<li>Flags that describe whether this identifier is the name of a built-in, a
+poisoned identifier, an extension token, or a macro.</li>
+<li>If the identifier names a macro, the offset of the macro definition within
+the <a class="reference internal" href="#pchinternals-preprocessor"><em>Preprocessor Block</em></a>.</li>
+<li>If the identifier names one or more declarations visible from translation
+unit scope, the <a class="reference internal" href="#pchinternals-decls"><em>declaration IDs</em></a> of these
+declarations.</li>
+</ul>
+<p>When an AST file is loaded, the AST file reader mechanism introduces itself
+into the identifier table as an external lookup source.  Thus, when the user
+program refers to an identifier that has not yet been seen, Clang will perform
+a lookup into the identifier table.  If an identifier is found, its contents
+(macro definitions, flags, top-level declarations, etc.) will be deserialized,
+at which point the corresponding <tt class="docutils literal"><span class="pre">IdentifierInfo</span></tt> structure will have the
+same contents it would have after parsing the headers in the AST file.</p>
+<p>Within the AST file, the identifiers used to name declarations are represented
+with an integral value.  A separate table provides a mapping from this integral
+value (the identifier ID) to the location within the on-disk hash table where
+that identifier is stored.  This mapping is used when deserializing the name of
+a declaration, the identifier of a token, or any other construct in the AST
+file that refers to a name.</p>
+</div>
+<div class="section" id="method-pool-block">
+<span id="pchinternals-method-pool"></span><h3><a class="toc-backref" href="#id11">Method Pool Block</a><a class="headerlink" href="#method-pool-block" title="Permalink to this headline">¶</a></h3>
+<p>The method pool block is represented as an on-disk hash table that serves two
+purposes: it provides a mapping from the names of Objective-C selectors to the
+set of Objective-C instance and class methods that have that particular
+selector (which is required for semantic analysis in Objective-C) and also
+stores all of the selectors used by entities within the AST file.  The design
+of the method pool is similar to that of the <a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>: the first time a particular selector is formed
+during the compilation of the program, Clang will search in the on-disk hash
+table of selectors; if found, Clang will read the Objective-C methods
+associated with that selector into the appropriate front-end data structure
+(<tt class="docutils literal"><span class="pre">Sema::InstanceMethodPool</span></tt> and <tt class="docutils literal"><span class="pre">Sema::FactoryMethodPool</span></tt> for instance and
+class methods, respectively).</p>
+<p>As with identifiers, selectors are represented by numeric values within the AST
+file.  A separate index maps these numeric selector values to the offset of the
+selector within the on-disk hash table, and will be used when de-serializing an
+Objective-C method declaration (or other Objective-C construct) that refers to
+the selector.</p>
+</div>
+</div>
+<div class="section" id="ast-reader-integration-points">
+<h2><a class="toc-backref" href="#id12">AST Reader Integration Points</a><a class="headerlink" href="#ast-reader-integration-points" title="Permalink to this headline">¶</a></h2>
+<p>The “lazy” deserialization behavior of AST files requires their integration
+into several completely different submodules of Clang.  For example, lazily
+deserializing the declarations during name lookup requires that the name-lookup
+routines be able to query the AST file to find entities stored there.</p>
+<p>For each Clang data structure that requires direct interaction with the AST
+reader logic, there is an abstract class that provides the interface between
+the two modules.  The <tt class="docutils literal"><span class="pre">ASTReader</span></tt> class, which handles the loading of an AST
+file, inherits from all of these abstract classes to provide lazy
+deserialization of Clang’s data structures.  <tt class="docutils literal"><span class="pre">ASTReader</span></tt> implements the
+following abstract classes:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">ExternalSLocEntrySource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">SourceManager</span></tt> class, and
+is used whenever the <a class="reference internal" href="#pchinternals-sourcemgr"><em>source manager</em></a> needs to
+load the details of a file, buffer, or macro instantiation.</dd>
+<dt><tt class="docutils literal"><span class="pre">IdentifierInfoLookup</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">IdentifierTable</span></tt> class, and
+is used whenever the program source refers to an identifier that has not yet
+been seen.  In this case, the AST reader searches for this identifier within
+its <a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a> to load any top-level
+declarations or macros associated with that identifier.</dd>
+<dt><tt class="docutils literal"><span class="pre">ExternalASTSource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">ASTContext</span></tt> class, and is
+used whenever the abstract syntax tree nodes need to loaded from the AST
+file.  It provides the ability to de-serialize declarations and types
+identified by their numeric values, read the bodies of functions when
+required, and read the declarations stored within a declaration context
+(either for iteration or for name lookup).</dd>
+<dt><tt class="docutils literal"><span class="pre">ExternalSemaSource</span></tt></dt>
+<dd>This abstract interface is associated with the <tt class="docutils literal"><span class="pre">Sema</span></tt> class, and is used
+whenever semantic analysis needs to read information from the <a class="reference internal" href="#pchinternals-method-pool"><em>global
+method pool</em></a>.</dd>
+</dl>
+</div>
+<div class="section" id="chained-precompiled-headers">
+<span id="pchinternals-chained"></span><h2><a class="toc-backref" href="#id13">Chained precompiled headers</a><a class="headerlink" href="#chained-precompiled-headers" title="Permalink to this headline">¶</a></h2>
+<p>Chained precompiled headers were initially intended to improve the performance
+of IDE-centric operations such as syntax highlighting and code completion while
+a particular source file is being edited by the user.  To minimize the amount
+of reparsing required after a change to the file, a form of precompiled header
+— called a precompiled <em>preamble</em> — is automatically generated by parsing
+all of the headers in the source file, up to and including the last
+<tt class="docutils literal"><span class="pre">#include</span></tt>.  When only the source file changes (and none of the headers it
+depends on), reparsing of that source file can use the precompiled preamble and
+start parsing after the <tt class="docutils literal"><span class="pre">#include</span></tt>s, so parsing time is proportional to the
+size of the source file (rather than all of its includes).  However, the
+compilation of that translation unit may already use a precompiled header: in
+this case, Clang will create the precompiled preamble as a chained precompiled
+header that refers to the original precompiled header.  This drastically
+reduces the time needed to serialize the precompiled preamble for use in
+reparsing.</p>
+<p>Chained precompiled headers get their name because each precompiled header can
+depend on one other precompiled header, forming a chain of dependencies.  A
+translation unit will then include the precompiled header that starts the chain
+(i.e., nothing depends on it).  This linearity of dependencies is important for
+the semantic model of chained precompiled headers, because the most-recent
+precompiled header can provide information that overrides the information
+provided by the precompiled headers it depends on, just like a header file
+<tt class="docutils literal"><span class="pre">B.h</span></tt> that includes another header <tt class="docutils literal"><span class="pre">A.h</span></tt> can modify the state produced by
+parsing <tt class="docutils literal"><span class="pre">A.h</span></tt>, e.g., by <tt class="docutils literal"><span class="pre">#undef</span></tt>‘ing a macro defined in <tt class="docutils literal"><span class="pre">A.h</span></tt>.</p>
+<p>There are several ways in which chained precompiled headers generalize the AST
+file model:</p>
+<dl class="docutils">
+<dt>Numbering of IDs</dt>
+<dd>Many different kinds of entities — identifiers, declarations, types, etc.
+— have ID numbers that start at 1 or some other predefined constant and
+grow upward.  Each precompiled header records the maximum ID number it has
+assigned in each category.  Then, when a new precompiled header is generated
+that depends on (chains to) another precompiled header, it will start
+counting at the next available ID number.  This way, one can determine, given
+an ID number, which AST file actually contains the entity.</dd>
+<dt>Name lookup</dt>
+<dd>When writing a chained precompiled header, Clang attempts to write only
+information that has changed from the precompiled header on which it is
+based.  This changes the lookup algorithm for the various tables, such as the
+<a class="reference internal" href="#pchinternals-ident-table"><em>identifier table</em></a>: the search starts at the
+most-recent precompiled header.  If no entry is found, lookup then proceeds
+to the identifier table in the precompiled header it depends on, and so one.
+Once a lookup succeeds, that result is considered definitive, overriding any
+results from earlier precompiled headers.</dd>
+<dt>Update records</dt>
+<dd>There are various ways in which a later precompiled header can modify the
+entities described in an earlier precompiled header.  For example, later
+precompiled headers can add entries into the various name-lookup tables for
+the translation unit or namespaces, or add new categories to an Objective-C
+class.  Each of these updates is captured in an “update record” that is
+stored in the chained precompiled header file and will be loaded along with
+the original entity.</dd>
+</dl>
+</div>
+<div class="section" id="modules">
+<span id="pchinternals-modules"></span><h2><a class="toc-backref" href="#id14">Modules</a><a class="headerlink" href="#modules" title="Permalink to this headline">¶</a></h2>
+<p>Modules generalize the chained precompiled header model yet further, from a
+linear chain of precompiled headers to an arbitrary directed acyclic graph
+(DAG) of AST files.  All of the same techniques used to make chained
+precompiled headers work — ID number, name lookup, update records — are
+shared with modules.  However, the DAG nature of modules introduce a number of
+additional complications to the model:</p>
+<dl class="docutils">
+<dt>Numbering of IDs</dt>
+<dd>The simple, linear numbering scheme used in chained precompiled headers falls
+apart with the module DAG, because different modules may end up with
+different numbering schemes for entities they imported from common shared
+modules.  To account for this, each module file provides information about
+which modules it depends on and which ID numbers it assigned to the entities
+in those modules, as well as which ID numbers it took for its own new
+entities.  The AST reader then maps these “local” ID numbers into a “global”
+ID number space for the current translation unit, providing a 1-1 mapping
+between entities (in whatever AST file they inhabit) and global ID numbers.
+If that translation unit is then serialized into an AST file, this mapping
+will be stored for use when the AST file is imported.</dd>
+<dt>Declaration merging</dt>
+<dd>It is possible for a given entity (from the language’s perspective) to be
+declared multiple times in different places.  For example, two different
+headers can have the declaration of <tt class="docutils literal"><span class="pre">printf</span></tt> or could forward-declare
+<tt class="docutils literal"><span class="pre">struct</span> <span class="pre">stat</span></tt>.  If each of those headers is included in a module, and some
+third party imports both of those modules, there is a potentially serious
+problem: name lookup for <tt class="docutils literal"><span class="pre">printf</span></tt> or <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">stat</span></tt> will find both
+declarations, but the AST nodes are unrelated.  This would result in a
+compilation error, due to an ambiguity in name lookup.  Therefore, the AST
+reader performs declaration merging according to the appropriate language
+semantics, ensuring that the two disjoint declarations are merged into a
+single redeclaration chain (with a common canonical declaration), so that it
+is as if one of the headers had been included before the other.</dd>
+<dt>Name Visibility</dt>
+<dd>Modules allow certain names that occur during module creation to be “hidden”,
+so that they are not part of the public interface of the module and are not
+visible to its clients.  The AST reader maintains a “visible” bit on various
+AST nodes (declarations, macros, etc.) to indicate whether that particular
+AST node is currently visible; the various name lookup mechanisms in Clang
+inspect the visible bit to determine whether that entity, which is still in
+the AST (because other, visible AST nodes may depend on it), can actually be
+found by name lookup.  When a new (sub)module is imported, it may make
+existing, non-visible, already-deserialized AST nodes visible; it is the
+responsibility of the AST reader to find and update these AST nodes when it
+is notified of the import.</dd>
+</dl>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="PTHInternals.html">Pretokenized Headers (PTH)</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ItaniumMangleAbiTags.html">ABI tags</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/PTHInternals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/PTHInternals.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/PTHInternals.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/PTHInternals.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,214 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Pretokenized Headers (PTH) — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="Precompiled Header and Modules Internals" href="PCHInternals.html" />
+    <link rel="prev" title="Driver Design & Internals" href="DriverInternals.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>Pretokenized Headers (PTH)</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="DriverInternals.html">Driver Design & Internals</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="PCHInternals.html">Precompiled Header and Modules Internals</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="pretokenized-headers-pth">
+<h1>Pretokenized Headers (PTH)<a class="headerlink" href="#pretokenized-headers-pth" title="Permalink to this headline">¶</a></h1>
+<p>This document first describes the low-level interface for using PTH and
+then briefly elaborates on its design and implementation. If you are
+interested in the end-user view, please see the <a class="reference internal" href="UsersManual.html#usersmanual-precompiled-headers"><em>User’s Manual</em></a>.</p>
+<div class="section" id="using-pretokenized-headers-with-clang-low-level-interface">
+<h2>Using Pretokenized Headers with <tt class="docutils literal"><span class="pre">clang</span></tt> (Low-level Interface)<a class="headerlink" href="#using-pretokenized-headers-with-clang-low-level-interface" title="Permalink to this headline">¶</a></h2>
+<p>The Clang compiler frontend, <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, supports three command line
+options for generating and using PTH files.</p>
+<p>To generate PTH files using <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt>, use the option <tt class="docutils literal"><span class="pre">-emit-pth</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 test.h -emit-pth -o test.h.pth
+</pre></div>
+</div>
+<p>This option is transparently used by <tt class="docutils literal"><span class="pre">clang</span></tt> when generating PTH
+files. Similarly, PTH files can be used as prefix headers using the
+<tt class="docutils literal"><span class="pre">-include-pth</span></tt> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -cc1 -include-pth test.h.pth test.c -o test.s
+</pre></div>
+</div>
+<p>Alternatively, Clang’s PTH files can be used as a raw “token-cache” (or
+“content” cache) of the source included by the original header file.
+This means that the contents of the PTH file are searched as substitutes
+for <em>any</em> source files that are used by <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> to process a
+source file. This is done by specifying the <tt class="docutils literal"><span class="pre">-token-cache</span></tt> option:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat test.h
+<span class="gp">#</span>include <stdio.h>
+<span class="gp">$</span> clang -cc1 -emit-pth test.h -o test.h.pth
+<span class="gp">$</span> cat test.c
+<span class="gp">#</span>include <span class="s2">"test.h"</span>
+<span class="gp">$</span> clang -cc1 test.c -o <span class="nb">test</span> -token-cache test.h.pth
+</pre></div>
+</div>
+<p>In this example the contents of <tt class="docutils literal"><span class="pre">stdio.h</span></tt> (and the files it includes)
+will be retrieved from <tt class="docutils literal"><span class="pre">test.h.pth</span></tt>, as the PTH file is being used in
+this case as a raw cache of the contents of <tt class="docutils literal"><span class="pre">test.h</span></tt>. This is a
+low-level interface used to both implement the high-level PTH interface
+as well as to provide alternative means to use PTH-style caching.</p>
+</div>
+<div class="section" id="pth-design-and-implementation">
+<h2>PTH Design and Implementation<a class="headerlink" href="#pth-design-and-implementation" title="Permalink to this headline">¶</a></h2>
+<p>Unlike GCC’s precompiled headers, which cache the full ASTs and
+preprocessor state of a header file, Clang’s pretokenized header files
+mainly cache the raw lexer <em>tokens</em> that are needed to segment the
+stream of characters in a source file into keywords, identifiers, and
+operators. Consequently, PTH serves to mainly directly speed up the
+lexing and preprocessing of a source file, while parsing and
+type-checking must be completely redone every time a PTH file is used.</p>
+<div class="section" id="basic-design-tradeoffs">
+<h3>Basic Design Tradeoffs<a class="headerlink" href="#basic-design-tradeoffs" title="Permalink to this headline">¶</a></h3>
+<p>In the long term there are plans to provide an alternate PCH
+implementation for Clang that also caches the work for parsing and type
+checking the contents of header files. The current implementation of PCH
+in Clang as pretokenized header files was motivated by the following
+factors:</p>
+<dl class="docutils">
+<dt><strong>Language independence</strong></dt>
+<dd>PTH files work with any language that
+Clang’s lexer can handle, including C, Objective-C, and (in the early
+stages) C++. This means development on language features at the
+parsing level or above (which is basically almost all interesting
+pieces) does not require PTH to be modified.</dd>
+<dt><strong>Simple design</strong></dt>
+<dd>Relatively speaking, PTH has a simple design and
+implementation, making it easy to test. Further, because the
+machinery for PTH resides at the lower-levels of the Clang library
+stack it is fairly straightforward to profile and optimize.</dd>
+</dl>
+<p>Further, compared to GCC’s PCH implementation (which is the dominate
+precompiled header file implementation that Clang can be directly
+compared against) the PTH design in Clang yields several attractive
+features:</p>
+<dl class="docutils">
+<dt><strong>Architecture independence</strong></dt>
+<dd><p class="first">In contrast to GCC’s PCH files (and
+those of several other compilers), Clang’s PTH files are architecture
+independent, requiring only a single PTH file when building a
+program for multiple architectures.</p>
+<p class="last">For example, on Mac OS X one may wish to compile a “universal binary”
+that runs on PowerPC, 32-bit Intel (i386), and 64-bit Intel
+architectures. In contrast, GCC requires a PCH file for each
+architecture, as the definitions of types in the AST are
+architecture-specific. Since a Clang PTH file essentially represents
+a lexical cache of header files, a single PTH file can be safely used
+when compiling for multiple architectures. This can also reduce
+compile times because only a single PTH file needs to be generated
+during a build instead of several.</p>
+</dd>
+<dt><strong>Reduced memory pressure</strong></dt>
+<dd>Similar to GCC, Clang reads PTH files
+via the use of memory mapping (i.e., <tt class="docutils literal"><span class="pre">mmap</span></tt>). Clang, however,
+memory maps PTH files as read-only, meaning that multiple invocations
+of <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> can share the same pages in memory from a
+memory-mapped PTH file. In comparison, GCC also memory maps its PCH
+files but also modifies those pages in memory, incurring the
+copy-on-write costs. The read-only nature of PTH can greatly reduce
+memory pressure for builds involving multiple cores, thus improving
+overall scalability.</dd>
+<dt><strong>Fast generation</strong></dt>
+<dd>PTH files can be generated in a small fraction
+of the time needed to generate GCC’s PCH files. Since PTH/PCH
+generation is a serial operation that typically blocks progress
+during a build, faster generation time leads to improved processor
+utilization with parallel builds on multicore machines.</dd>
+</dl>
+<p>Despite these strengths, PTH’s simple design suffers some algorithmic
+handicaps compared to other PCH strategies such as those used by GCC.
+While PTH can greatly speed up the processing time of a header file, the
+amount of work required to process a header file is still roughly linear
+in the size of the header file. In contrast, the amount of work done by
+GCC to process a precompiled header is (theoretically) constant (the
+ASTs for the header are literally memory mapped into the compiler). This
+means that only the pieces of the header file that are referenced by the
+source file including the header are the only ones the compiler needs to
+process during actual compilation. While GCC’s particular implementation
+of PCH mitigates some of these algorithmic strengths via the use of
+copy-on-write pages, the approach itself can fundamentally dominate at
+an algorithmic level, especially when one considers header files of
+arbitrary size.</p>
+<p>There is also a PCH implementation for Clang based on the lazy
+deserialization of ASTs. This approach theoretically has the same
+constant-time algorithmic advantages just mentioned but also retains some
+of the strengths of PTH such as reduced memory pressure (ideal for
+multi-core builds).</p>
+</div>
+<div class="section" id="internal-pth-optimizations">
+<h3>Internal PTH Optimizations<a class="headerlink" href="#internal-pth-optimizations" title="Permalink to this headline">¶</a></h3>
+<p>While the main optimization employed by PTH is to reduce lexing time of
+header files by caching pre-lexed tokens, PTH also employs several other
+optimizations to speed up the processing of header files:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">stat</span></tt> caching: PTH files cache information obtained via calls to
+<tt class="docutils literal"><span class="pre">stat</span></tt> that <tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-cc1</span></tt> uses to resolve which files are included
+by <tt class="docutils literal"><span class="pre">#include</span></tt> directives. This greatly reduces the overhead
+involved in context-switching to the kernel to resolve included
+files.</li>
+<li>Fast skipping of <tt class="docutils literal"><span class="pre">#ifdef</span></tt> ... <tt class="docutils literal"><span class="pre">#endif</span></tt> chains: PTH files
+record the basic structure of nested preprocessor blocks. When the
+condition of the preprocessor block is false, all of its tokens are
+immediately skipped instead of requiring them to be handled by
+Clang’s preprocessor.</li>
+</ul>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="DriverInternals.html">Driver Design & Internals</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="PCHInternals.html">Precompiled Header and Modules Internals</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/RAVFrontendAction.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/RAVFrontendAction.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/RAVFrontendAction.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/RAVFrontendAction.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,266 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>How to write RecursiveASTVisitor based ASTFrontendActions. — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="Tutorial for building tools using LibTooling and LibASTMatchers" href="LibASTMatchersTutorial.html" />
+    <link rel="prev" title="Clang Plugins" href="ClangPlugins.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>How to write RecursiveASTVisitor based ASTFrontendActions.</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="ClangPlugins.html">Clang Plugins</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="how-to-write-recursiveastvisitor-based-astfrontendactions">
+<h1>How to write RecursiveASTVisitor based ASTFrontendActions.<a class="headerlink" href="#how-to-write-recursiveastvisitor-based-astfrontendactions" 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>In this tutorial you will learn how to create a FrontendAction that uses
+a RecursiveASTVisitor to find CXXRecordDecl AST nodes with a specified
+name.</p>
+</div>
+<div class="section" id="creating-a-frontendaction">
+<h2>Creating a FrontendAction<a class="headerlink" href="#creating-a-frontendaction" title="Permalink to this headline">¶</a></h2>
+<p>When writing a clang based tool like a Clang Plugin or a standalone tool
+based on LibTooling, the common entry point is the FrontendAction.
+FrontendAction is an interface that allows execution of user specific
+actions as part of the compilation. To run tools over the AST clang
+provides the convenience interface ASTFrontendAction, which takes care
+of executing the action. The only part left is to implement the
+CreateASTConsumer method that returns an ASTConsumer per translation
+unit.</p>
+<div class="highlight-python"><div class="highlight"><pre>class FindNamedClassAction : public clang::ASTFrontendAction {
+public:
+  virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+    clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+    return std::unique_ptr<clang::ASTConsumer>(
+        new FindNamedClassConsumer);
+  }
+};
+</pre></div>
+</div>
+</div>
+<div class="section" id="creating-an-astconsumer">
+<h2>Creating an ASTConsumer<a class="headerlink" href="#creating-an-astconsumer" title="Permalink to this headline">¶</a></h2>
+<p>ASTConsumer is an interface used to write generic actions on an AST,
+regardless of how the AST was produced. ASTConsumer provides many
+different entry points, but for our use case the only one needed is
+HandleTranslationUnit, which is called with the ASTContext for the
+translation unit.</p>
+<div class="highlight-python"><div class="highlight"><pre>class FindNamedClassConsumer : public clang::ASTConsumer {
+public:
+  virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+    // Traversing the translation unit decl via a RecursiveASTVisitor
+    // will visit all nodes in the AST.
+    Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+  }
+private:
+  // A RecursiveASTVisitor implementation.
+  FindNamedClassVisitor Visitor;
+};
+</pre></div>
+</div>
+</div>
+<div class="section" id="using-the-recursiveastvisitor">
+<h2>Using the RecursiveASTVisitor<a class="headerlink" href="#using-the-recursiveastvisitor" title="Permalink to this headline">¶</a></h2>
+<p>Now that everything is hooked up, the next step is to implement a
+RecursiveASTVisitor to extract the relevant information from the AST.</p>
+<p>The RecursiveASTVisitor provides hooks of the form bool
+VisitNodeType(NodeType *) for most AST nodes; the exception are TypeLoc
+nodes, which are passed by-value. We only need to implement the methods
+for the relevant node types.</p>
+<p>Let’s start by writing a RecursiveASTVisitor that visits all
+CXXRecordDecl’s.</p>
+<div class="highlight-python"><div class="highlight"><pre>class FindNamedClassVisitor
+  : public RecursiveASTVisitor<FindNamedClassVisitor> {
+public:
+  bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+    // For debugging, dumping the AST nodes will show which nodes are already
+    // being visited.
+    Declaration->dump();
+
+    // The return value indicates whether we want the visitation to proceed.
+    // Return false to stop the traversal of the AST.
+    return true;
+  }
+};
+</pre></div>
+</div>
+<p>In the methods of our RecursiveASTVisitor we can now use the full power
+of the Clang AST to drill through to the parts that are interesting for
+us. For example, to find all class declaration with a certain name, we
+can check for a specific qualified name:</p>
+<div class="highlight-python"><div class="highlight"><pre>bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+  if (Declaration->getQualifiedNameAsString() == "n::m::C")
+    Declaration->dump();
+  return true;
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="accessing-the-sourcemanager-and-astcontext">
+<h2>Accessing the SourceManager and ASTContext<a class="headerlink" href="#accessing-the-sourcemanager-and-astcontext" title="Permalink to this headline">¶</a></h2>
+<p>Some of the information about the AST, like source locations and global
+identifier information, are not stored in the AST nodes themselves, but
+in the ASTContext and its associated source manager. To retrieve them we
+need to hand the ASTContext into our RecursiveASTVisitor implementation.</p>
+<p>The ASTContext is available from the CompilerInstance during the call to
+CreateASTConsumer. We can thus extract it there and hand it into our
+freshly created FindNamedClassConsumer:</p>
+<div class="highlight-python"><div class="highlight"><pre>virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+  clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+  return std::unique_ptr<clang::ASTConsumer>(
+      new FindNamedClassConsumer(&Compiler.getASTContext()));
+}
+</pre></div>
+</div>
+<p>Now that the ASTContext is available in the RecursiveASTVisitor, we can
+do more interesting things with AST nodes, like looking up their source
+locations:</p>
+<div class="highlight-python"><div class="highlight"><pre>bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+  if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+    // getFullLoc uses the ASTContext's SourceManager to resolve the source
+    // location and break it up into its line and column parts.
+    FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+    if (FullLocation.isValid())
+      llvm::outs() << "Found declaration at "
+                   << FullLocation.getSpellingLineNumber() << ":"
+                   << FullLocation.getSpellingColumnNumber() << "\n";
+  }
+  return true;
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="putting-it-all-together">
+<h2>Putting it all together<a class="headerlink" href="#putting-it-all-together" title="Permalink to this headline">¶</a></h2>
+<p>Now we can combine all of the above into a small example program:</p>
+<div class="highlight-python"><div class="highlight"><pre>#include "clang/AST/ASTConsumer.h"
+#include "clang/AST/RecursiveASTVisitor.h"
+#include "clang/Frontend/CompilerInstance.h"
+#include "clang/Frontend/FrontendAction.h"
+#include "clang/Tooling/Tooling.h"
+
+using namespace clang;
+
+class FindNamedClassVisitor
+  : public RecursiveASTVisitor<FindNamedClassVisitor> {
+public:
+  explicit FindNamedClassVisitor(ASTContext *Context)
+    : Context(Context) {}
+
+  bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+    if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+      FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+      if (FullLocation.isValid())
+        llvm::outs() << "Found declaration at "
+                     << FullLocation.getSpellingLineNumber() << ":"
+                     << FullLocation.getSpellingColumnNumber() << "\n";
+    }
+    return true;
+  }
+
+private:
+  ASTContext *Context;
+};
+
+class FindNamedClassConsumer : public clang::ASTConsumer {
+public:
+  explicit FindNamedClassConsumer(ASTContext *Context)
+    : Visitor(Context) {}
+
+  virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+    Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+  }
+private:
+  FindNamedClassVisitor Visitor;
+};
+
+class FindNamedClassAction : public clang::ASTFrontendAction {
+public:
+  virtual std::unique_ptr<clang::ASTConsumer> CreateASTConsumer(
+    clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+    return std::unique_ptr<clang::ASTConsumer>(
+        new FindNamedClassConsumer(&Compiler.getASTContext()));
+  }
+};
+
+int main(int argc, char **argv) {
+  if (argc > 1) {
+    clang::tooling::runToolOnCode(new FindNamedClassAction, argv[1]);
+  }
+}
+</pre></div>
+</div>
+<p>We store this into a file called FindClassDecls.cpp and create the
+following CMakeLists.txt to link it:</p>
+<div class="highlight-python"><div class="highlight"><pre>add_clang_executable(find-class-decls FindClassDecls.cpp)
+
+target_link_libraries(find-class-decls clangTooling)
+</pre></div>
+</div>
+<p>When running this tool over a small code snippet it will output all
+declarations of a class n::m::C it found:</p>
+<div class="highlight-python"><div class="highlight"><pre>$ ./bin/find-class-decls "namespace n { namespace m { class C {}; } }"
+Found declaration at 1:29
+</pre></div>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="ClangPlugins.html">Clang Plugins</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LibASTMatchersTutorial.html">Tutorial for building tools using LibTooling and LibASTMatchers</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/ReleaseNotes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/ReleaseNotes.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/ReleaseNotes.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/ReleaseNotes.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,336 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Clang 3.9 Release Notes — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="Clang Compiler User’s Manual" href="UsersManual.html" />
+    <link rel="prev" title="Using Clang as a Compiler" href="index.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>Clang 3.9 Release Notes</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="index.html">Using Clang as a Compiler</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="UsersManual.html">Clang Compiler User’s Manual</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="clang-3-9-release-notes">
+<h1>Clang 3.9 Release Notes<a class="headerlink" href="#clang-3-9-release-notes" 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="id2">Introduction</a></li>
+<li><a class="reference internal" href="#what-s-new-in-clang-3-9" id="id3">What’s New in Clang 3.9?</a><ul>
+<li><a class="reference internal" href="#major-new-features" id="id4">Major New Features</a></li>
+<li><a class="reference internal" href="#attribute-changes-in-clang" id="id5">Attribute Changes in Clang</a></li>
+<li><a class="reference internal" href="#windows-support" id="id6">Windows Support</a></li>
+<li><a class="reference internal" href="#c-language-changes-in-clang" id="id7">C Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#id1" id="id8">C++ Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#opencl-c-language-changes-in-clang" id="id9">OpenCL C Language Changes in Clang</a></li>
+<li><a class="reference internal" href="#openmp-support-in-clang" id="id10">OpenMP Support in Clang</a></li>
+<li><a class="reference internal" href="#ast-matchers" id="id11">AST Matchers</a></li>
+<li><a class="reference internal" href="#static-analyzer" id="id12">Static Analyzer</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#additional-information" id="id13">Additional Information</a></li>
+</ul>
+</div>
+<p>Written by the <a class="reference external" href="http://llvm.org/">LLVM Team</a></p>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains the release notes for the Clang C/C++/Objective-C
+frontend, part of the LLVM Compiler Infrastructure, release 3.9. Here we
+describe the status of Clang in some detail, including major
+improvements from the previous release and new feature work. For the
+general LLVM release notes, see <a class="reference external" href="http://llvm.org/docs/ReleaseNotes.html">the LLVM
+documentation</a>. All LLVM
+releases may be downloaded from the <a class="reference external" href="http://llvm.org/releases/">LLVM releases web
+site</a>.</p>
+<p>For more information about Clang or LLVM, including information about
+the latest release, please check out the main please see the <a class="reference external" href="http://clang.llvm.org">Clang Web
+Site</a> or the <a class="reference external" href="http://llvm.org">LLVM Web
+Site</a>.</p>
+</div>
+<div class="section" id="what-s-new-in-clang-3-9">
+<h2><a class="toc-backref" href="#id3">What’s New in Clang 3.9?</a><a class="headerlink" href="#what-s-new-in-clang-3-9" title="Permalink to this headline">¶</a></h2>
+<p>Some of the major new features and improvements to Clang are listed
+here. Generic improvements to Clang as a whole or to its underlying
+infrastructure are described first, followed by language-specific
+sections with improvements to Clang’s support for those languages.</p>
+<div class="section" id="major-new-features">
+<h3><a class="toc-backref" href="#id4">Major New Features</a><a class="headerlink" href="#major-new-features" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Clang will no longer pass <tt class="docutils literal"><span class="pre">--build-id</span></tt> by default to the linker. In modern
+linkers that is a relatively expensive option. It can be passed explicitly
+with <tt class="docutils literal"><span class="pre">-Wl,--build-id</span></tt>. To have clang always pass it, build clang with
+<tt class="docutils literal"><span class="pre">-DENABLE_LINKER_BUILD_ID</span></tt>.</li>
+<li>On Itanium ABI targets, attribute abi_tag is now supported for compatibility
+with GCC. Clang’s implementation of abi_tag is mostly compatible with GCC ABI
+version 10.</li>
+</ul>
+<div class="section" id="improvements-to-clang-s-diagnostics">
+<h4>Improvements to Clang’s diagnostics<a class="headerlink" href="#improvements-to-clang-s-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>Clang’s diagnostics are constantly being improved to catch more issues,
+explain them more clearly, and provide more accurate source information
+about them. The improvements since the 3.8 release include:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-Wcomma</span></tt> is a new warning to show most uses of the builtin comma operator.</li>
+<li><tt class="docutils literal"><span class="pre">-Wfloat-conversion</span></tt> has two new sub-warnings to give finer grain control for
+floating point to integer conversion warnings.<ul>
+<li><tt class="docutils literal"><span class="pre">-Wfloat-overflow-conversion</span></tt> detects when a constant floating point value
+is converted to an integer type and will overflow the target type.</li>
+<li><tt class="docutils literal"><span class="pre">-Wfloat-zero-conversion</span></tt> detects when a non-zero floating point value is
+converted to a zero integer value.</li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="attribute-changes-in-clang">
+<h3><a class="toc-backref" href="#id5">Attribute Changes in Clang</a><a class="headerlink" href="#attribute-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>The <tt class="docutils literal"><span class="pre">nodebug</span></tt> attribute may now be applied to static, global, and local
+variables (but not parameters or non-static data members). This will suppress
+all debugging information for the variable (and its type, if there are no
+other uses of the type).</li>
+</ul>
+</div>
+<div class="section" id="windows-support">
+<h3><a class="toc-backref" href="#id6">Windows Support</a><a class="headerlink" href="#windows-support" title="Permalink to this headline">¶</a></h3>
+<p>TLS is enabled for Cygwin and defaults to -femulated-tls.</p>
+<p>Proper support, including correct mangling and overloading, added for
+MS-specific “__unaligned” type qualifier.</p>
+<p>clang-cl now has limited support for the precompiled header flags /Yc, /Yu, and
+/Fp.  If the precompiled header is passed on the compile command with /FI, then
+the precompiled header flags are honored.  But if the precompiled header is
+included by an <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><stdafx.h></span></tt> in each source file instead of by a
+<tt class="docutils literal"><span class="pre">/FIstdafx.h</span></tt> flag, these flag continue to be ignored.</p>
+<p>clang-cl has a new flag, <tt class="docutils literal"><span class="pre">/imsvc</span> <span class="pre"><dir></span></tt>, for adding a directory to the system
+include search path (where warnings are disabled by default) without having to
+set <tt class="docutils literal"><span class="pre">%INCLUDE%</span></tt>.</p>
+</div>
+<div class="section" id="c-language-changes-in-clang">
+<h3><a class="toc-backref" href="#id7">C Language Changes in Clang</a><a class="headerlink" href="#c-language-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<p>The -faltivec and -maltivec flags no longer silently include altivec.h on Power platforms.</p>
+<p><a class="reference external" href="https://developer.android.com/guide/topics/renderscript/compute.html">RenderScript</a>
+support has been added to the frontend and enabled by the ‘-x renderscript’
+option or the ‘.rs’ file extension.</p>
+</div>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id8">C++ Language Changes in Clang</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<ul>
+<li><p class="first">Clang now enforces the rule that a <em>using-declaration</em> cannot name an enumerator of a
+scoped enumeration.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">Foo</span> <span class="p">{</span> <span class="k">enum</span> <span class="k">class</span> <span class="nc">E</span> <span class="p">{</span> <span class="n">e</span> <span class="p">};</span> <span class="p">}</span>
+<span class="k">namespace</span> <span class="n">Bar</span> <span class="p">{</span>
+  <span class="k">using</span> <span class="n">Foo</span><span class="o">::</span><span class="n">E</span><span class="o">::</span><span class="n">e</span><span class="p">;</span> <span class="c1">// error</span>
+  <span class="n">constexpr</span> <span class="k">auto</span> <span class="n">e</span> <span class="o">=</span> <span class="n">Foo</span><span class="o">::</span><span class="n">E</span><span class="o">::</span><span class="n">e</span><span class="p">;</span> <span class="c1">// ok</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Clang now enforces the rule that an enumerator of an unscoped enumeration declared at
+class scope can only be named by a <em>using-declaration</em> in a derived class.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span> <span class="k">enum</span> <span class="n">E</span> <span class="p">{</span> <span class="n">e</span> <span class="p">};</span> <span class="p">}</span>
+<span class="k">using</span> <span class="n">Foo</span><span class="o">::</span><span class="n">e</span><span class="p">;</span> <span class="c1">// error</span>
+<span class="k">static</span> <span class="n">constexpr</span> <span class="k">auto</span> <span class="n">e</span> <span class="o">=</span> <span class="n">Foo</span><span class="o">::</span><span class="n">e</span><span class="p">;</span> <span class="c1">// ok</span>
+</pre></div>
+</div>
+</li>
+</ul>
+<div class="section" id="c-1z-feature-support">
+<h4>C++1z Feature Support<a class="headerlink" href="#c-1z-feature-support" title="Permalink to this headline">¶</a></h4>
+<p>Clang’s experimental support for the upcoming C++1z standard can be enabled with <tt class="docutils literal"><span class="pre">-std=c++1z</span></tt>.
+Changes to C++1z features since Clang 3.8:</p>
+<ul>
+<li><p class="first">The <tt class="docutils literal"><span class="pre">[[fallthrough]]</span></tt>, <tt class="docutils literal"><span class="pre">[[nodiscard]]</span></tt>, and <tt class="docutils literal"><span class="pre">[[maybe_unused]]</span></tt> attributes are
+supported in C++11 onwards, and are largely synonymous with Clang’s existing attributes
+<tt class="docutils literal"><span class="pre">[[clang::fallthrough]]</span></tt>, <tt class="docutils literal"><span class="pre">[[gnu::warn_unused_result]]</span></tt>, and <tt class="docutils literal"><span class="pre">[[gnu::unused]]</span></tt>.
+Use <tt class="docutils literal"><span class="pre">-Wimplicit-fallthrough</span></tt> to warn on unannotated fallthrough within <tt class="docutils literal"><span class="pre">switch</span></tt>
+statements.</p>
+</li>
+<li><p class="first">In C++1z mode, aggregate initialization can be performed for classes with base classes:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">A</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">n</span><span class="p">;</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">B</span> <span class="o">:</span> <span class="n">A</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">;</span> <span class="p">};</span>
+<span class="n">B</span> <span class="n">b</span> <span class="o">=</span> <span class="p">{</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span> <span class="p">};</span> <span class="c1">// b.n == 1, b.x == 2, b.y == 3</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">The range in a range-based <tt class="docutils literal"><span class="pre">for</span></tt> statement can have different types for its <tt class="docutils literal"><span class="pre">begin</span></tt>
+and <tt class="docutils literal"><span class="pre">end</span></tt> iterators. This is permitted as an extension in C++11 onwards.</p>
+</li>
+<li><p class="first">Lambda-expressions can explicitly capture <tt class="docutils literal"><span class="pre">*this</span></tt> (to capture the surrounding object
+by copy). This is permitted as an extension in C++11 onwards.</p>
+</li>
+<li><p class="first">Objects of enumeration type can be direct-list-initialized from a value of the underlying
+type. <tt class="docutils literal"><span class="pre">E{n}</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">E(n)</span></tt>, except that it implies a check for a narrowing
+conversion.</p>
+</li>
+<li><p class="first">Unary <em>fold-expression</em>s over an empty pack are now rejected for all operators
+other than <tt class="docutils literal"><span class="pre">&&</span></tt>, <tt class="docutils literal"><span class="pre">||</span></tt>, and <tt class="docutils literal"><span class="pre">,</span></tt>.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="opencl-c-language-changes-in-clang">
+<h3><a class="toc-backref" href="#id9">OpenCL C Language Changes in Clang</a><a class="headerlink" href="#opencl-c-language-changes-in-clang" title="Permalink to this headline">¶</a></h3>
+<p>Clang now has support for all OpenCL 2.0 features.  In particular, the following
+features have been completed since the previous release:</p>
+<ul class="simple">
+<li>Pipe builtin functions (s6.13.16.2-4).</li>
+<li>Dynamic parallelism support via the <tt class="docutils literal"><span class="pre">enqueue_kernel</span></tt> Clang builtin function,
+as well as the kernel query functions from s6.13.17.6.</li>
+<li>Address space conversion functions <tt class="docutils literal"><span class="pre">to_{global/local/private}</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">nosvm</span></tt> attribute support.</li>
+<li>Improved diagnostic and generation of Clang Blocks used in OpenCL kernel code.</li>
+<li><tt class="docutils literal"><span class="pre">opencl_unroll_hint</span></tt> pragma.</li>
+</ul>
+<p>Several miscellaneous improvements have been made:</p>
+<ul>
+<li><p class="first">Supported extensions are now part of the target representation to give correct
+diagnostics for unsupported target features during compilation. For example,
+when compiling for a target that does not support the double precision
+floating point extension, Clang will give an error when encountering the
+<tt class="docutils literal"><span class="pre">cl_khr_fp64</span></tt> pragma. Several missing extensions were added covering up to
+and including OpenCL 2.0.</p>
+</li>
+<li><p class="first">Clang now comes with the OpenCL standard headers declaring builtin types and
+functions up to and including OpenCL 2.0 in <tt class="docutils literal"><span class="pre">lib/Headers/opencl-c.h</span></tt>. By
+default, Clang will not include this header. It can be included either using
+the regular <tt class="docutils literal"><span class="pre">-I<path</span> <span class="pre">to</span> <span class="pre">header</span> <span class="pre">location></span></tt> directive or (if the default one
+from installation is to be used) using the <tt class="docutils literal"><span class="pre">-finclude-default-header</span></tt>
+frontend flag.</p>
+<p>Example:</p>
+<div class="highlight-none"><div class="highlight"><pre>echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl
+clang -cc1 -finclude-default-header -cl-std=CL2.0 test.cl
+</pre></div>
+</div>
+<p>All builtin function declarations from OpenCL 2.0 will be automatically
+visible in test.cl.</p>
+</li>
+<li><p class="first">Image types have been improved with better diagnostics for access qualifiers.
+Images with one access qualifier type cannot be used in declarations for
+another type. Also qualifiers are now propagated from the frontend down to
+libraries and backends.</p>
+</li>
+<li><p class="first">Diagnostic improvements for OpenCL types, address spaces and vectors.</p>
+</li>
+<li><p class="first">Half type literal support has been added. For example, <tt class="docutils literal"><span class="pre">1.0h</span></tt> represents a
+floating point literal in half precision, i.e., the value <tt class="docutils literal"><span class="pre">0xH3C00</span></tt>.</p>
+</li>
+<li><p class="first">The Clang driver now accepts OpenCL compiler options <tt class="docutils literal"><span class="pre">-cl-*</span></tt> (following the
+OpenCL Spec v1.1-1.2 s5.8). For example, the <tt class="docutils literal"><span class="pre">-cl-std=CL1.2</span></tt> option from the
+spec enables compilation for OpenCL 1.2, or <tt class="docutils literal"><span class="pre">-cl-mad-enable</span></tt> will enable
+fusing multiply-and-add operations.</p>
+</li>
+<li><p class="first">Clang now uses function metadata instead of module metadata to propagate
+information related to OpenCL kernels e.g. kernel argument information.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="openmp-support-in-clang">
+<h3><a class="toc-backref" href="#id10">OpenMP Support in Clang</a><a class="headerlink" href="#openmp-support-in-clang" title="Permalink to this headline">¶</a></h3>
+<p>Added support for all non-offloading features from OpenMP 4.5, including using
+data members in private clauses of non-static member functions. Additionally,
+data members can be used as loop control variables in loop-based directives.</p>
+<p>Currently Clang supports OpenMP 3.1 and all non-offloading features of
+OpenMP 4.0/4.5. Offloading features are under development. Clang defines macro
+_OPENMP and sets it to OpenMP 3.1 (in accordance with OpenMP standard) by
+default. User may change this value using <tt class="docutils literal"><span class="pre">-fopenmp-version=[31|40|45]</span></tt> option.</p>
+<p>The codegen for OpenMP constructs was significantly improved to produce much
+more stable and faster code.</p>
+</div>
+<div class="section" id="ast-matchers">
+<h3><a class="toc-backref" href="#id11">AST Matchers</a><a class="headerlink" href="#ast-matchers" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>has and hasAnyArgument: Matchers no longer ignore parentheses and implicit
+casts on the argument before applying the inner matcher. The fix was done to
+allow for greater control by the user. In all existing checkers that use this
+matcher all instances of code <tt class="docutils literal"><span class="pre">hasAnyArgument(<inner</span> <span class="pre">matcher>)</span></tt> or
+<tt class="docutils literal"><span class="pre">has(<inner</span> <span class="pre">matcher>)</span></tt> must be changed to
+<tt class="docutils literal"><span class="pre">hasAnyArgument(ignoringParenImpCasts(<inner</span> <span class="pre">matcher>))</span></tt> or
+<tt class="docutils literal"><span class="pre">has(ignoringParenImpCasts(<inner</span> <span class="pre">matcher>))</span></tt>.</li>
+</ul>
+</div>
+<div class="section" id="static-analyzer">
+<h3><a class="toc-backref" href="#id12">Static Analyzer</a><a class="headerlink" href="#static-analyzer" title="Permalink to this headline">¶</a></h3>
+<p>The analyzer now checks for incorrect usage of MPI APIs in C and C++. This
+check can be enabled by passing the following command to scan-build:
+<tt class="docutils literal"><span class="pre">-enable-checker</span> <span class="pre">optin.mpi.MPI-Checker.</span></tt></p>
+<p>The analyzer now checks for improper instance cleanup up in Objective-C
+<tt class="docutils literal"><span class="pre">-dealloc</span></tt> methods under manual retain/release.</p>
+<p>On Windows, checks for memory leaks, double frees, and use-after-free problems
+are now enabled by default.</p>
+<p>The analyzer now includes scan-build-py, an experimental reimplementation of
+scan-build in Python that also creates compilation databases.</p>
+<p>The scan-build tool now supports a <tt class="docutils literal"><span class="pre">--force-analyze-debug-code</span></tt> flag that
+forces projects to analyze in debug mode. This flag leaves in assertions and so
+typically results in fewer false positives.</p>
+</div>
+</div>
+<div class="section" id="additional-information">
+<h2><a class="toc-backref" href="#id13">Additional Information</a><a class="headerlink" href="#additional-information" title="Permalink to this headline">¶</a></h2>
+<p>A wide variety of additional information is available on the <a class="reference external" href="http://clang.llvm.org/">Clang web
+page</a>. The web page contains versions of the
+API documentation which are up-to-date with the Subversion version of
+the source code. You can access versions of these documents specific to
+this release by going into the “<tt class="docutils literal"><span class="pre">clang/docs/</span></tt>” directory in the Clang
+tree.</p>
+<p>If you have any questions or comments about Clang, please feel free to
+contact us via the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/cfe-dev">mailing
+list</a>.</p>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="index.html">Using Clang as a Compiler</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="UsersManual.html">Clang Compiler User’s Manual</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/SafeStack.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/SafeStack.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/SafeStack.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/SafeStack.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,268 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>SafeStack — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="Source-based Code Coverage" href="SourceBasedCodeCoverage.html" />
+    <link rel="prev" title="LTO Visibility" href="LTOVisibility.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>SafeStack</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="LTOVisibility.html">LTO Visibility</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="SourceBasedCodeCoverage.html">Source-based Code Coverage</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="safestack">
+<h1>SafeStack<a class="headerlink" href="#safestack" 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><ul>
+<li><a class="reference internal" href="#performance" id="id2">Performance</a></li>
+<li><a class="reference internal" href="#compatibility" id="id3">Compatibility</a><ul>
+<li><a class="reference internal" href="#known-compatibility-limitations" id="id4">Known compatibility limitations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#security" id="id5">Security</a><ul>
+<li><a class="reference internal" href="#known-security-limitations" id="id6">Known security limitations</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#usage" id="id7">Usage</a><ul>
+<li><a class="reference internal" href="#supported-platforms" id="id8">Supported Platforms</a></li>
+<li><a class="reference internal" href="#low-level-api" id="id9">Low-level API</a><ul>
+<li><a class="reference internal" href="#has-feature-safe-stack" id="id10"><tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt></a></li>
+<li><a class="reference internal" href="#attribute-no-sanitize-safe-stack" id="id11"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt></a></li>
+<li><a class="reference internal" href="#builtin-get-unsafe-stack-ptr" id="id12"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_ptr()</span></tt></a></li>
+<li><a class="reference internal" href="#builtin-get-unsafe-stack-start" id="id13"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_start()</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#design" id="id14">Design</a><ul>
+<li><a class="reference internal" href="#setjmp-and-exception-handling" id="id15">setjmp and exception handling</a></li>
+<li><a class="reference internal" href="#publications" id="id16">Publications</a></li>
+</ul>
+</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>SafeStack is an instrumentation pass that protects programs against attacks
+based on stack buffer overflows, without introducing any measurable performance
+overhead. It works by separating the program stack into two distinct regions:
+the safe stack and the unsafe stack. The safe stack stores return addresses,
+register spills, and local variables that are always accessed in a safe way,
+while the unsafe stack stores everything else. This separation ensures that
+buffer overflows on the unsafe stack cannot be used to overwrite anything
+on the safe stack.</p>
+<p>SafeStack is a part of the <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">Code-Pointer Integrity (CPI) Project</a>.</p>
+<div class="section" id="performance">
+<h3><a class="toc-backref" href="#id2">Performance</a><a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h3>
+<p>The performance overhead of the SafeStack instrumentation is less than 0.1% on
+average across a variety of benchmarks (see the <a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">Code-Pointer Integrity</a> paper for details). This is mainly
+because most small functions do not have any variables that require the unsafe
+stack and, hence, do not need unsafe stack frames to be created. The cost of
+creating unsafe stack frames for large functions is amortized by the cost of
+executing the function.</p>
+<p>In some cases, SafeStack actually improves the performance. Objects that end up
+being moved to the unsafe stack are usually large arrays or variables that are
+used through multiple stack frames. Moving such objects away from the safe
+stack increases the locality of frequently accessed values on the stack, such
+as register spills, return addresses, and small local variables.</p>
+</div>
+<div class="section" id="compatibility">
+<h3><a class="toc-backref" href="#id3">Compatibility</a><a class="headerlink" href="#compatibility" title="Permalink to this headline">¶</a></h3>
+<p>Most programs, static libraries, or individual files can be compiled
+with SafeStack as is. SafeStack requires basic runtime support, which, on most
+platforms, is implemented as a compiler-rt library that is automatically linked
+in when the program is compiled with SafeStack.</p>
+<p>Linking a DSO with SafeStack is not currently supported.</p>
+<div class="section" id="known-compatibility-limitations">
+<h4><a class="toc-backref" href="#id4">Known compatibility limitations</a><a class="headerlink" href="#known-compatibility-limitations" title="Permalink to this headline">¶</a></h4>
+<p>Certain code that relies on low-level stack manipulations requires adaption to
+work with SafeStack. One example is mark-and-sweep garbage collection
+implementations for C/C++ (e.g., Oilpan in chromium/blink), which must be
+changed to look for the live pointers on both safe and unsafe stacks.</p>
+<p>SafeStack supports linking statically modules that are compiled with and
+without SafeStack. An executable compiled with SafeStack can load dynamic
+libraries that are not compiled with SafeStack. At the moment, compiling
+dynamic libraries with SafeStack is not supported.</p>
+<p>Signal handlers that use <tt class="docutils literal"><span class="pre">sigaltstack()</span></tt> must not use the unsafe stack (see
+<tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt> below).</p>
+<p>Programs that use APIs from <tt class="docutils literal"><span class="pre">ucontext.h</span></tt> are not supported yet.</p>
+</div>
+</div>
+<div class="section" id="security">
+<h3><a class="toc-backref" href="#id5">Security</a><a class="headerlink" href="#security" title="Permalink to this headline">¶</a></h3>
+<p>SafeStack protects return addresses, spilled registers and local variables that
+are always accessed in a safe way by separating them in a dedicated safe stack
+region. The safe stack is automatically protected against stack-based buffer
+overflows, since it is disjoint from the unsafe stack in memory, and it itself
+is always accessed in a safe way. In the current implementation, the safe stack
+is protected against arbitrary memory write vulnerabilities though
+randomization and information hiding: the safe stack is allocated at a random
+address and the instrumentation ensures that no pointers to the safe stack are
+ever stored outside of the safe stack itself (see limitations below).</p>
+<div class="section" id="known-security-limitations">
+<h4><a class="toc-backref" href="#id6">Known security limitations</a><a class="headerlink" href="#known-security-limitations" title="Permalink to this headline">¶</a></h4>
+<p>A complete protection against control-flow hijack attacks requires combining
+SafeStack with another mechanism that enforces the integrity of code pointers
+that are stored on the heap or the unsafe stack, such as <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">CPI</a>, or a forward-edge control flow integrity
+mechanism that enforces correct calling conventions at indirect call sites,
+such as <a class="reference external" href="http://research.google.com/pubs/archive/42808.pdf">IFCC</a> with arity
+checks. Clang has control-flow integrity protection scheme for <a class="reference internal" href="ControlFlowIntegrity.html"><em>C++ virtual
+calls</em></a>, but not non-virtual indirect calls. With
+SafeStack alone, an attacker can overwrite a function pointer on the heap or
+the unsafe stack and cause a program to call arbitrary location, which in turn
+might enable stack pivoting and return-oriented programming.</p>
+<p>In its current implementation, SafeStack provides precise protection against
+stack-based buffer overflows, but protection against arbitrary memory write
+vulnerabilities is probabilistic and relies on randomization and information
+hiding. The randomization is currently based on system-enforced ASLR and shares
+its known security limitations. The safe stack pointer hiding is not perfect
+yet either: system library functions such as <tt class="docutils literal"><span class="pre">swapcontext</span></tt>, exception
+handling mechanisms, intrinsics such as <tt class="docutils literal"><span class="pre">__builtin_frame_address</span></tt>, or
+low-level bugs in runtime support could leak the safe stack pointer. In the
+future, such leaks could be detected by static or dynamic analysis tools and
+prevented by adjusting such functions to either encrypt the stack pointer when
+storing it in the heap (as already done e.g., by <tt class="docutils literal"><span class="pre">setjmp</span></tt>/<tt class="docutils literal"><span class="pre">longjmp</span></tt>
+implementation in glibc), or store it in a safe region instead.</p>
+<p>The <a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">CPI paper</a> describes two alternative,
+stronger safe stack protection mechanisms, that rely on software fault
+isolation, or hardware segmentation (as available on x86-32 and some x86-64
+CPUs).</p>
+<p>At the moment, SafeStack assumes that the compiler’s implementation is correct.
+This has not been verified except through manual code inspection, and could
+always regress in the future. It’s therefore desirable to have a separate
+static or dynamic binary verification tool that would check the correctness of
+the SafeStack instrumentation in final binaries.</p>
+</div>
+</div>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id7">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>To enable SafeStack, just pass <tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt> flag to both compile
+and link command lines.</p>
+<div class="section" id="supported-platforms">
+<h3><a class="toc-backref" href="#id8">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h3>
+<p>SafeStack was tested on Linux, FreeBSD and MacOSX.</p>
+</div>
+<div class="section" id="low-level-api">
+<h3><a class="toc-backref" href="#id9">Low-level API</a><a class="headerlink" href="#low-level-api" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="has-feature-safe-stack">
+<h4><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt></a><a class="headerlink" href="#has-feature-safe-stack" title="Permalink to this headline">¶</a></h4>
+<p>In some rare cases one may need to execute different code depending on
+whether SafeStack is enabled. The macro <tt class="docutils literal"><span class="pre">__has_feature(safe_stack)</span></tt> can
+be used for this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#if __has_feature(safe_stack)</span>
+<span class="c1">// code that builds only under SafeStack</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="attribute-no-sanitize-safe-stack">
+<h4><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt></a><a class="headerlink" href="#attribute-no-sanitize-safe-stack" title="Permalink to this headline">¶</a></h4>
+<p>Use <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("safe-stack")))</span></tt> on a function declaration
+to specify that the safe stack instrumentation should not be applied to that
+function, even if enabled globally (see <tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt> flag). This
+attribute may be required for functions that make assumptions about the
+exact layout of their stack frames.</p>
+<p>All local variables in functions with this attribute will be stored on the safe
+stack. The safe stack remains unprotected against memory errors when accessing
+these variables, so extra care must be taken to manually ensure that all such
+accesses are safe. Furthermore, the addresses of such local variables should
+never be stored on the heap, as it would leak the location of the SafeStack.</p>
+</div>
+<div class="section" id="builtin-get-unsafe-stack-ptr">
+<h4><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_ptr()</span></tt></a><a class="headerlink" href="#builtin-get-unsafe-stack-ptr" title="Permalink to this headline">¶</a></h4>
+<p>This builtin function returns current unsafe stack pointer of the current
+thread.</p>
+</div>
+<div class="section" id="builtin-get-unsafe-stack-start">
+<h4><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">__builtin___get_unsafe_stack_start()</span></tt></a><a class="headerlink" href="#builtin-get-unsafe-stack-start" title="Permalink to this headline">¶</a></h4>
+<p>This builtin function returns a pointer to the start of the unsafe stack of the
+current thread.</p>
+</div>
+</div>
+</div>
+<div class="section" id="design">
+<h2><a class="toc-backref" href="#id14">Design</a><a class="headerlink" href="#design" title="Permalink to this headline">¶</a></h2>
+<p>Please refer to the <a class="reference external" href="http://dslab.epfl.ch/proj/cpi/">Code-Pointer Integrity</a>
+project page for more information about the design of the SafeStack and its
+related technologies.</p>
+<div class="section" id="setjmp-and-exception-handling">
+<h3><a class="toc-backref" href="#id15">setjmp and exception handling</a><a class="headerlink" href="#setjmp-and-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>The <a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">OSDI‘14 paper</a> mentions that
+on Linux the instrumentation pass finds calls to setjmp or functions that
+may throw an exception, and inserts required instrumentation at their call
+sites. Specifically, the instrumentation pass saves the shadow stack pointer
+on the safe stack before the call site, and restores it either after the
+call to setjmp or after an exception has been caught. This is implemented
+in the function <tt class="docutils literal"><span class="pre">SafeStack::createStackRestorePoints</span></tt>.</p>
+</div>
+<div class="section" id="publications">
+<h3><a class="toc-backref" href="#id16">Publications</a><a class="headerlink" href="#publications" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://dslab.epfl.ch/pubs/cpi.pdf">Code-Pointer Integrity</a>.
+Volodymyr Kuznetsov, Laszlo Szekeres, Mathias Payer, George Candea, R. Sekar, Dawn Song.
+USENIX Symposium on Operating Systems Design and Implementation
+(<a class="reference external" href="https://www.usenix.org/conference/osdi14">OSDI</a>), Broomfield, CO, October 2014</p>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="LTOVisibility.html">LTO Visibility</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="SourceBasedCodeCoverage.html">Source-based Code Coverage</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/SanitizerCoverage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/SanitizerCoverage.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/SanitizerCoverage.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/SanitizerCoverage.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,644 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>SanitizerCoverage — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="SanitizerStats" href="SanitizerStats.html" />
+    <link rel="prev" title="LeakSanitizer" href="LeakSanitizer.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>SanitizerCoverage</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="LeakSanitizer.html">LeakSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="SanitizerStats.html">SanitizerStats</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="sanitizercoverage">
+<h1>SanitizerCoverage<a class="headerlink" href="#sanitizercoverage" 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-and-run" id="id2">How to build and run</a></li>
+<li><a class="reference internal" href="#postprocessing" id="id3">Postprocessing</a></li>
+<li><a class="reference internal" href="#sancov-tool" id="id4">Sancov Tool</a></li>
+<li><a class="reference internal" href="#automatic-html-report-generation" id="id5">Automatic HTML Report Generation</a></li>
+<li><a class="reference internal" href="#how-good-is-the-coverage" id="id6">How good is the coverage?</a></li>
+<li><a class="reference internal" href="#edge-coverage" id="id7">Edge coverage</a></li>
+<li><a class="reference internal" href="#bitset" id="id8">Bitset</a></li>
+<li><a class="reference internal" href="#caller-callee-coverage" id="id9">Caller-callee coverage</a></li>
+<li><a class="reference internal" href="#coverage-counters" id="id10">Coverage counters</a></li>
+<li><a class="reference internal" href="#tracing-basic-blocks" id="id11">Tracing basic blocks</a></li>
+<li><a class="reference internal" href="#tracing-pcs" id="id12">Tracing PCs</a></li>
+<li><a class="reference internal" href="#tracing-data-flow" id="id13">Tracing data flow</a></li>
+<li><a class="reference internal" href="#output-directory" id="id14">Output directory</a></li>
+<li><a class="reference internal" href="#sudden-death" id="id15">Sudden death</a></li>
+<li><a class="reference internal" href="#in-process-fuzzing" id="id16">In-process fuzzing</a></li>
+<li><a class="reference internal" href="#performance" id="id17">Performance</a></li>
+<li><a class="reference internal" href="#why-another-coverage" id="id18">Why another coverage?</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>Sanitizer tools have a very simple code coverage tool built in. It allows to
+get function-level, basic-block-level, and edge-level coverage at a very low
+cost.</p>
+</div>
+<div class="section" id="how-to-build-and-run">
+<h2><a class="toc-backref" href="#id2">How to build and run</a><a class="headerlink" href="#how-to-build-and-run" title="Permalink to this headline">¶</a></h2>
+<p>SanitizerCoverage can be used with <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>,
+<a class="reference internal" href="LeakSanitizer.html"><em>LeakSanitizer</em></a>, <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a>,
+UndefinedBehaviorSanitizer, or without any sanitizer.  Pass one of the
+following compile-time flags:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-fsanitize-coverage=func</span></tt> for function-level coverage (very fast).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize-coverage=bb</span></tt> for basic-block-level coverage (may add up to 30%
+<strong>extra</strong> slowdown).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize-coverage=edge</span></tt> for edge-level coverage (up to 40% slowdown).</li>
+</ul>
+<p>You may also specify <tt class="docutils literal"><span class="pre">-fsanitize-coverage=indirect-calls</span></tt> for
+additional <a class="reference internal" href="#caller-callee-coverage">caller-callee coverage</a>.</p>
+<p>At run time, pass <tt class="docutils literal"><span class="pre">coverage=1</span></tt> in <tt class="docutils literal"><span class="pre">ASAN_OPTIONS</span></tt>,
+<tt class="docutils literal"><span class="pre">LSAN_OPTIONS</span></tt>, <tt class="docutils literal"><span class="pre">MSAN_OPTIONS</span></tt> or <tt class="docutils literal"><span class="pre">UBSAN_OPTIONS</span></tt>, as
+appropriate. For the standalone coverage mode, use <tt class="docutils literal"><span class="pre">UBSAN_OPTIONS</span></tt>.</p>
+<p>To get <a class="reference internal" href="#coverage-counters">Coverage counters</a>, add <tt class="docutils literal"><span class="pre">-fsanitize-coverage=8bit-counters</span></tt>
+to one of the above compile-time flags. At runtime, use
+<tt class="docutils literal"><span class="pre">*SAN_OPTIONS=coverage=1:coverage_counters=1</span></tt>.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> cat -n cov.cc
+<span class="go">     1  #include <stdio.h></span>
+<span class="go">     2  __attribute__((noinline))</span>
+<span class="go">     3  void foo() { printf("foo\n"); }</span>
+<span class="go">     4</span>
+<span class="go">     5  int main(int argc, char **argv) {</span>
+<span class="go">     6    if (argc == 2)</span>
+<span class="go">     7      foo();</span>
+<span class="go">     8    printf("main\n");</span>
+<span class="go">     9  }</span>
+<span class="gp">%</span> clang++ -g cov.cc -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>func
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">coverage</span><span class="o">=</span>1 ./a.out; ls -l *sancov
+<span class="go">main</span>
+<span class="go">-rw-r----- 1 kcc eng 4 Nov 27 12:21 a.out.22673.sancov</span>
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">coverage</span><span class="o">=</span>1 ./a.out foo ; ls -l *sancov
+<span class="go">foo</span>
+<span class="go">main</span>
+<span class="go">-rw-r----- 1 kcc eng 4 Nov 27 12:21 a.out.22673.sancov</span>
+<span class="go">-rw-r----- 1 kcc eng 8 Nov 27 12:21 a.out.22679.sancov</span>
+</pre></div>
+</div>
+<p>Every time you run an executable instrumented with SanitizerCoverage
+one <tt class="docutils literal"><span class="pre">*.sancov</span></tt> file is created during the process shutdown.
+If the executable is dynamically linked against instrumented DSOs,
+one <tt class="docutils literal"><span class="pre">*.sancov</span></tt> file will be also created for every DSO.</p>
+</div>
+<div class="section" id="postprocessing">
+<h2><a class="toc-backref" href="#id3">Postprocessing</a><a class="headerlink" href="#postprocessing" title="Permalink to this headline">¶</a></h2>
+<p>The format of <tt class="docutils literal"><span class="pre">*.sancov</span></tt> files is very simple: the first 8 bytes is the magic,
+one of <tt class="docutils literal"><span class="pre">0xC0BFFFFFFFFFFF64</span></tt> and <tt class="docutils literal"><span class="pre">0xC0BFFFFFFFFFFF32</span></tt>. The last byte of the
+magic defines the size of the following offsets. The rest of the data is the
+offsets in the corresponding binary/DSO that were executed during the run.</p>
+<p>A simple script
+<tt class="docutils literal"><span class="pre">$LLVM/projects/compiler-rt/lib/sanitizer_common/scripts/sancov.py</span></tt> is
+provided to dump these offsets.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> sancov.py print a.out.22679.sancov a.out.22673.sancov
+<span class="go">sancov.py: read 2 PCs from a.out.22679.sancov</span>
+<span class="go">sancov.py: read 1 PCs from a.out.22673.sancov</span>
+<span class="go">sancov.py: 2 files merged; 2 PCs total</span>
+<span class="go">0x465250</span>
+<span class="go">0x4652a0</span>
+</pre></div>
+</div>
+<p>You can then filter the output of <tt class="docutils literal"><span class="pre">sancov.py</span></tt> through <tt class="docutils literal"><span class="pre">addr2line</span> <span class="pre">--exe</span>
+<span class="pre">ObjectFile</span></tt> or <tt class="docutils literal"><span class="pre">llvm-symbolizer</span> <span class="pre">--obj</span> <span class="pre">ObjectFile</span></tt> to get file names and line
+numbers:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> sancov.py print a.out.22679.sancov a.out.22673.sancov 2> /dev/null | llvm-symbolizer --obj a.out
+<span class="go">cov.cc:3</span>
+<span class="go">cov.cc:5</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="sancov-tool">
+<h2><a class="toc-backref" href="#id4">Sancov Tool</a><a class="headerlink" href="#sancov-tool" title="Permalink to this headline">¶</a></h2>
+<p>A new experimental <tt class="docutils literal"><span class="pre">sancov</span></tt> tool is developed to process coverage files.
+The tool is part of LLVM project and is currently supported only on Linux.
+It can handle symbolization tasks autonomously without any extra support
+from the environment. You need to pass .sancov files (named
+<tt class="docutils literal"><span class="pre"><module_name>.<pid>.sancov</span></tt> and paths to all corresponding binary elf files.
+Sancov matches these files using module names and binaries file names.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">USAGE: sancov [options] <action> (<binary file>|<.sancov file>)...</span>
+
+<span class="go">Action (required)</span>
+<span class="go">  -print                    - Print coverage addresses</span>
+<span class="go">  -covered-functions        - Print all covered functions.</span>
+<span class="go">  -not-covered-functions    - Print all not covered functions.</span>
+<span class="go">  -html-report              - Print HTML coverage report.</span>
+
+<span class="go">Options</span>
+<span class="go">  -blacklist=<string>         - Blacklist file (sanitizer blacklist format).</span>
+<span class="go">  -demangle                   - Print demangled function name.</span>
+<span class="go">  -strip_path_prefix=<string> - Strip this prefix from file paths in reports</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="automatic-html-report-generation">
+<h2><a class="toc-backref" href="#id5">Automatic HTML Report Generation</a><a class="headerlink" href="#automatic-html-report-generation" title="Permalink to this headline">¶</a></h2>
+<p>If <tt class="docutils literal"><span class="pre">*SAN_OPTIONS</span></tt> contains <tt class="docutils literal"><span class="pre">html_cov_report=1</span></tt> option set, then html
+coverage report would be automatically generated alongside the coverage files.
+The <tt class="docutils literal"><span class="pre">sancov</span></tt> binary should be present in <tt class="docutils literal"><span class="pre">PATH</span></tt> or
+<tt class="docutils literal"><span class="pre">sancov_path=<path_to_sancov</span></tt> option can be used to specify tool location.</p>
+</div>
+<div class="section" id="how-good-is-the-coverage">
+<h2><a class="toc-backref" href="#id6">How good is the coverage?</a><a class="headerlink" href="#how-good-is-the-coverage" title="Permalink to this headline">¶</a></h2>
+<p>It is possible to find out which PCs are not covered, by subtracting the covered
+set from the set of all instrumented PCs. The latter can be obtained by listing
+all callsites of <tt class="docutils literal"><span class="pre">__sanitizer_cov()</span></tt> in the binary. On Linux, <tt class="docutils literal"><span class="pre">sancov.py</span></tt>
+can do this for you. Just supply the path to binary and a list of covered PCs:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> sancov.py print a.out.12345.sancov > covered.txt
+<span class="go">sancov.py: read 2 64-bit PCs from a.out.12345.sancov</span>
+<span class="go">sancov.py: 1 file merged; 2 PCs total</span>
+<span class="gp">%</span> sancov.py missing a.out < covered.txt
+<span class="go">sancov.py: found 3 instrumented PCs in a.out</span>
+<span class="go">sancov.py: read 2 PCs from stdin</span>
+<span class="go">sancov.py: 1 PCs missing from coverage</span>
+<span class="go">0x4cc61c</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="edge-coverage">
+<h2><a class="toc-backref" href="#id7">Edge coverage</a><a class="headerlink" href="#edge-coverage" title="Permalink to this headline">¶</a></h2>
+<p>Consider this code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">a</span><span class="p">)</span>
+    <span class="o">*</span><span class="n">a</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>It contains 3 basic blocks, let’s name them A, B, C:</p>
+<div class="highlight-none"><div class="highlight"><pre>A
+|\
+| \
+|  B
+| /
+|/
+C
+</pre></div>
+</div>
+<p>If blocks A, B, and C are all covered we know for certain that the edges A=>B
+and B=>C were executed, but we still don’t know if the edge A=>C was executed.
+Such edges of control flow graph are called
+<a class="reference external" href="http://en.wikipedia.org/wiki/Control_flow_graph#Special_edges">critical</a>. The
+edge-level coverage (<tt class="docutils literal"><span class="pre">-fsanitize-coverage=edge</span></tt>) simply splits all critical
+edges by introducing new dummy blocks and then instruments those blocks:</p>
+<div class="highlight-none"><div class="highlight"><pre>A
+|\
+| \
+D  B
+| /
+|/
+C
+</pre></div>
+</div>
+</div>
+<div class="section" id="bitset">
+<h2><a class="toc-backref" href="#id8">Bitset</a><a class="headerlink" href="#bitset" title="Permalink to this headline">¶</a></h2>
+<p>When <tt class="docutils literal"><span class="pre">coverage_bitset=1</span></tt> run-time flag is given, the coverage will also be
+dumped as a bitset (text file with 1 for blocks that have been executed and 0
+for blocks that were not).</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang++ -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>edge cov.cc
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_bitset=1"</span> ./a.out
+<span class="go">main</span>
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_bitset=1"</span> ./a.out 1
+<span class="go">foo</span>
+<span class="go">main</span>
+<span class="gp">%</span> head *bitset*
+<span class="go">==> a.out.38214.bitset-sancov <==</span>
+<span class="go">01101</span>
+<span class="go">==> a.out.6128.bitset-sancov <==</span>
+<span class="go">11011%</span>
+</pre></div>
+</div>
+<p>For a given executable the length of the bitset is always the same (well,
+unless dlopen/dlclose come into play), so the bitset coverage can be
+easily used for bitset-based corpus distillation.</p>
+</div>
+<div class="section" id="caller-callee-coverage">
+<h2><a class="toc-backref" href="#id9">Caller-callee coverage</a><a class="headerlink" href="#caller-callee-coverage" title="Permalink to this headline">¶</a></h2>
+<p>(Experimental!)
+Every indirect function call is instrumented with a run-time function call that
+captures caller and callee.  At the shutdown time the process dumps a separate
+file called <tt class="docutils literal"><span class="pre">caller-callee.PID.sancov</span></tt> which contains caller/callee pairs as
+pairs of lines (odd lines are callers, even lines are callees)</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">a.out 0x4a2e0c</span>
+<span class="go">a.out 0x4a6510</span>
+<span class="go">a.out 0x4a2e0c</span>
+<span class="go">a.out 0x4a87f0</span>
+</pre></div>
+</div>
+<p>Current limitations:</p>
+<ul class="simple">
+<li>Only the first 14 callees for every caller are recorded, the rest are silently
+ignored.</li>
+<li>The output format is not very compact since caller and callee may reside in
+different modules and we need to spell out the module names.</li>
+<li>The routine that dumps the output is not optimized for speed</li>
+<li>Only Linux x86_64 is tested so far.</li>
+<li>Sandboxes are not supported.</li>
+</ul>
+</div>
+<div class="section" id="coverage-counters">
+<h2><a class="toc-backref" href="#id10">Coverage counters</a><a class="headerlink" href="#coverage-counters" title="Permalink to this headline">¶</a></h2>
+<p>This experimental feature is inspired by
+<a class="reference external" href="http://lcamtuf.coredump.cx/afl/technical_details.txt">AFL</a>‘s coverage
+instrumentation. With additional compile-time and run-time flags you can get
+more sensitive coverage information.  In addition to boolean values assigned to
+every basic block (edge) the instrumentation will collect imprecise counters.
+On exit, every counter will be mapped to a 8-bit bitset representing counter
+ranges: <tt class="docutils literal"><span class="pre">1,</span> <span class="pre">2,</span> <span class="pre">3,</span> <span class="pre">4-7,</span> <span class="pre">8-15,</span> <span class="pre">16-31,</span> <span class="pre">32-127,</span> <span class="pre">128+</span></tt> and those 8-bit bitsets will
+be dumped to disk.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang++ -g cov.cc -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>edge,8bit-counters
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_counters=1"</span> ./a.out
+<span class="gp">%</span> ls -l *counters-sancov
+<span class="go">... a.out.17110.counters-sancov</span>
+<span class="gp">%</span> xxd *counters-sancov
+<span class="go">0000000: 0001 0100 01</span>
+</pre></div>
+</div>
+<p>These counters may also be used for in-process coverage-guided fuzzers. See
+<tt class="docutils literal"><span class="pre">include/sanitizer/coverage_interface.h</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// The coverage instrumentation may optionally provide imprecise counters.</span>
+<span class="c1">// Rather than exposing the counter values to the user we instead map</span>
+<span class="c1">// the counters to a bitset.</span>
+<span class="c1">// Every counter is associated with 8 bits in the bitset.</span>
+<span class="c1">// We define 8 value ranges: 1, 2, 3, 4-7, 8-15, 16-31, 32-127, 128+</span>
+<span class="c1">// The i-th bit is set to 1 if the counter value is in the i-th range.</span>
+<span class="c1">// This counter-based coverage implementation is *not* thread-safe.</span>
+
+<span class="c1">// Returns the number of registered coverage counters.</span>
+<span class="kt">uintptr_t</span> <span class="nf">__sanitizer_get_number_of_counters</span><span class="p">();</span>
+<span class="c1">// Updates the counter 'bitset', clears the counters and returns the number of</span>
+<span class="c1">// new bits in 'bitset'.</span>
+<span class="c1">// If 'bitset' is nullptr, only clears the counters.</span>
+<span class="c1">// Otherwise 'bitset' should be at least</span>
+<span class="c1">// __sanitizer_get_number_of_counters bytes long and 8-aligned.</span>
+<span class="kt">uintptr_t</span>
+<span class="nf">__sanitizer_update_counter_bitset_and_clear_counters</span><span class="p">(</span><span class="kt">uint8_t</span> <span class="o">*</span><span class="n">bitset</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="tracing-basic-blocks">
+<h2><a class="toc-backref" href="#id11">Tracing basic blocks</a><a class="headerlink" href="#tracing-basic-blocks" title="Permalink to this headline">¶</a></h2>
+<p>Experimental support for basic block (or edge) tracing.
+With <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-bb</span></tt> the compiler will insert
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_trace_basic_block(s32</span> <span class="pre">*id)</span></tt> before every function, basic block, or edge
+(depending on the value of <tt class="docutils literal"><span class="pre">-fsanitize-coverage=[func,bb,edge]</span></tt>).
+Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> clang -g -fsanitize<span class="o">=</span>address -fsanitize-coverage<span class="o">=</span>edge,trace-bb foo.cc
+<span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="nv">coverage</span><span class="o">=</span>1 ./a.out
+</pre></div>
+</div>
+<p>This will produce two files after the process exit:
+<cite>trace-points.PID.sancov</cite> and <cite>trace-events.PID.sancov</cite>.
+The first file will contain a textual description of all the instrumented points in the program
+in the form that you can feed into llvm-symbolizer (e.g. <cite>a.out 0x4dca89</cite>), one per line.
+The second file will contain the actual execution trace as a sequence of 4-byte integers
+– these integers are the indices into the array of instrumented points (the first file).</p>
+<p>Basic block tracing is currently supported only for single-threaded applications.</p>
+</div>
+<div class="section" id="tracing-pcs">
+<h2><a class="toc-backref" href="#id12">Tracing PCs</a><a class="headerlink" href="#tracing-pcs" title="Permalink to this headline">¶</a></h2>
+<p><em>Experimental</em> feature similar to tracing basic blocks, but with a different API.
+With <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-pc</span></tt> the compiler will insert
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc()</span></tt> on every edge.
+With an additional <tt class="docutils literal"><span class="pre">...=trace-pc,indirect-calls</span></tt> flag
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_trace_pc_indirect(void</span> <span class="pre">*callee)</span></tt> will be inserted on every indirect call.
+These callbacks are not implemented in the Sanitizer run-time and should be defined
+by the user. So, these flags do not require the other sanitizer to be used.
+This mechanism is used for fuzzing the Linux kernel (<a class="reference external" href="https://github.com/google/syzkaller">https://github.com/google/syzkaller</a>)
+and can be used with <a class="reference external" href="http://lcamtuf.coredump.cx/afl">AFL</a>.</p>
+</div>
+<div class="section" id="tracing-data-flow">
+<h2><a class="toc-backref" href="#id13">Tracing data flow</a><a class="headerlink" href="#tracing-data-flow" title="Permalink to this headline">¶</a></h2>
+<p>An <em>experimental</em> feature to support data-flow-guided fuzzing.
+With <tt class="docutils literal"><span class="pre">-fsanitize-coverage=trace-cmp</span></tt> the compiler will insert extra instrumentation
+around comparison instructions and switch statements.
+The fuzzer will need to define the following functions,
+they will be called by the instrumented code.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// Called before a comparison instruction.</span>
+<span class="c1">// SizeAndType is a packed value containing</span>
+<span class="c1">//   - [63:32] the Size of the operands of comparison in bits</span>
+<span class="c1">//   - [31:0] the Type of comparison (one of ICMP_EQ, ... ICMP_SLE)</span>
+<span class="c1">// Arg1 and Arg2 are arguments of the comparison.</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_cmp</span><span class="p">(</span><span class="kt">uint64_t</span> <span class="n">SizeAndType</span><span class="p">,</span> <span class="kt">uint64_t</span> <span class="n">Arg1</span><span class="p">,</span> <span class="kt">uint64_t</span> <span class="n">Arg2</span><span class="p">);</span>
+
+<span class="c1">// Called before a switch statement.</span>
+<span class="c1">// Val is the switch operand.</span>
+<span class="c1">// Cases[0] is the number of case constants.</span>
+<span class="c1">// Cases[1] is the size of Val in bits.</span>
+<span class="c1">// Cases[2:] are the case constants.</span>
+<span class="kt">void</span> <span class="nf">__sanitizer_cov_trace_switch</span><span class="p">(</span><span class="kt">uint64_t</span> <span class="n">Val</span><span class="p">,</span> <span class="kt">uint64_t</span> <span class="o">*</span><span class="n">Cases</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This interface is a subject to change.
+The current implementation is not thread-safe and thus can be safely used only for single-threaded targets.</p>
+</div>
+<div class="section" id="output-directory">
+<h2><a class="toc-backref" href="#id14">Output directory</a><a class="headerlink" href="#output-directory" title="Permalink to this headline">¶</a></h2>
+<p>By default, .sancov files are created in the current working directory.
+This can be changed with <tt class="docutils literal"><span class="pre">ASAN_OPTIONS=coverage_dir=/path</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_dir=/tmp/cov"</span> ./a.out foo
+<span class="gp">%</span> ls -l /tmp/cov/*sancov
+<span class="go">-rw-r----- 1 kcc eng 4 Nov 27 12:21 a.out.22673.sancov</span>
+<span class="go">-rw-r----- 1 kcc eng 8 Nov 27 12:21 a.out.22679.sancov</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="sudden-death">
+<h2><a class="toc-backref" href="#id15">Sudden death</a><a class="headerlink" href="#sudden-death" title="Permalink to this headline">¶</a></h2>
+<p>Normally, coverage data is collected in memory and saved to disk when the
+program exits (with an <tt class="docutils literal"><span class="pre">atexit()</span></tt> handler), when a SIGSEGV is caught, or when
+<tt class="docutils literal"><span class="pre">__sanitizer_cov_dump()</span></tt> is called.</p>
+<p>If the program ends with a signal that ASan does not handle (or can not handle
+at all, like SIGKILL), coverage data will be lost. This is a big problem on
+Android, where SIGKILL is a normal way of evicting applications from memory.</p>
+<p>With <tt class="docutils literal"><span class="pre">ASAN_OPTIONS=coverage=1:coverage_direct=1</span></tt> coverage data is written to a
+memory-mapped file as soon as it collected.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> <span class="nv">ASAN_OPTIONS</span><span class="o">=</span><span class="s2">"coverage=1:coverage_direct=1"</span> ./a.out
+<span class="go">main</span>
+<span class="gp">%</span> ls
+<span class="go">7036.sancov.map  7036.sancov.raw  a.out</span>
+<span class="gp">%</span> sancov.py rawunpack 7036.sancov.raw
+<span class="go">sancov.py: reading map 7036.sancov.map</span>
+<span class="go">sancov.py: unpacking 7036.sancov.raw</span>
+<span class="go">writing 1 PCs to a.out.7036.sancov</span>
+<span class="gp">%</span> sancov.py print a.out.7036.sancov
+<span class="go">sancov.py: read 1 PCs from a.out.7036.sancov</span>
+<span class="go">sancov.py: 1 files merged; 1 PCs total</span>
+<span class="go">0x4b2bae</span>
+</pre></div>
+</div>
+<p>Note that on 64-bit platforms, this method writes 2x more data than the default,
+because it stores full PC values instead of 32-bit offsets.</p>
+</div>
+<div class="section" id="in-process-fuzzing">
+<h2><a class="toc-backref" href="#id16">In-process fuzzing</a><a class="headerlink" href="#in-process-fuzzing" title="Permalink to this headline">¶</a></h2>
+<p>Coverage data could be useful for fuzzers and sometimes it is preferable to run
+a fuzzer in the same process as the code being fuzzed (in-process fuzzer).</p>
+<p>You can use <tt class="docutils literal"><span class="pre">__sanitizer_get_total_unique_coverage()</span></tt> from
+<tt class="docutils literal"><span class="pre"><sanitizer/coverage_interface.h></span></tt> which returns the number of currently
+covered entities in the program. This will tell the fuzzer if the coverage has
+increased after testing every new input.</p>
+<p>If a fuzzer finds a bug in the ASan run, you will need to save the reproducer
+before exiting the process.  Use <tt class="docutils literal"><span class="pre">__asan_set_death_callback</span></tt> from
+<tt class="docutils literal"><span class="pre"><sanitizer/asan_interface.h></span></tt> to do that.</p>
+<p>An example of such fuzzer can be found in <a class="reference external" href="http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Fuzzer/README.txt?view=markup">the LLVM tree</a>.</p>
+</div>
+<div class="section" id="performance">
+<h2><a class="toc-backref" href="#id17">Performance</a><a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h2>
+<p>This coverage implementation is <strong>fast</strong>. With function-level coverage
+(<tt class="docutils literal"><span class="pre">-fsanitize-coverage=func</span></tt>) the overhead is not measurable. With
+basic-block-level coverage (<tt class="docutils literal"><span class="pre">-fsanitize-coverage=bb</span></tt>) the overhead varies
+between 0 and 25%.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="21%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+<col width="13%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">benchmark</th>
+<th class="head">cov0</th>
+<th class="head">cov1</th>
+<th class="head">diff 0-1</th>
+<th class="head">cov2</th>
+<th class="head">diff 0-2</th>
+<th class="head">diff 1-2</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>400.perlbench</td>
+<td>1296.00</td>
+<td>1307.00</td>
+<td>1.01</td>
+<td>1465.00</td>
+<td>1.13</td>
+<td>1.12</td>
+</tr>
+<tr class="row-odd"><td>401.bzip2</td>
+<td>858.00</td>
+<td>854.00</td>
+<td>1.00</td>
+<td>1010.00</td>
+<td>1.18</td>
+<td>1.18</td>
+</tr>
+<tr class="row-even"><td>403.gcc</td>
+<td>613.00</td>
+<td>617.00</td>
+<td>1.01</td>
+<td>683.00</td>
+<td>1.11</td>
+<td>1.11</td>
+</tr>
+<tr class="row-odd"><td>429.mcf</td>
+<td>605.00</td>
+<td>582.00</td>
+<td>0.96</td>
+<td>610.00</td>
+<td>1.01</td>
+<td>1.05</td>
+</tr>
+<tr class="row-even"><td>445.gobmk</td>
+<td>896.00</td>
+<td>880.00</td>
+<td>0.98</td>
+<td>1050.00</td>
+<td>1.17</td>
+<td>1.19</td>
+</tr>
+<tr class="row-odd"><td>456.hmmer</td>
+<td>892.00</td>
+<td>892.00</td>
+<td>1.00</td>
+<td>918.00</td>
+<td>1.03</td>
+<td>1.03</td>
+</tr>
+<tr class="row-even"><td>458.sjeng</td>
+<td>995.00</td>
+<td>1009.00</td>
+<td>1.01</td>
+<td>1217.00</td>
+<td>1.22</td>
+<td>1.21</td>
+</tr>
+<tr class="row-odd"><td>462.libquantum</td>
+<td>497.00</td>
+<td>492.00</td>
+<td>0.99</td>
+<td>534.00</td>
+<td>1.07</td>
+<td>1.09</td>
+</tr>
+<tr class="row-even"><td>464.h264ref</td>
+<td>1461.00</td>
+<td>1467.00</td>
+<td>1.00</td>
+<td>1543.00</td>
+<td>1.06</td>
+<td>1.05</td>
+</tr>
+<tr class="row-odd"><td>471.omnetpp</td>
+<td>575.00</td>
+<td>590.00</td>
+<td>1.03</td>
+<td>660.00</td>
+<td>1.15</td>
+<td>1.12</td>
+</tr>
+<tr class="row-even"><td>473.astar</td>
+<td>658.00</td>
+<td>652.00</td>
+<td>0.99</td>
+<td>715.00</td>
+<td>1.09</td>
+<td>1.10</td>
+</tr>
+<tr class="row-odd"><td>483.xalancbmk</td>
+<td>471.00</td>
+<td>491.00</td>
+<td>1.04</td>
+<td>582.00</td>
+<td>1.24</td>
+<td>1.19</td>
+</tr>
+<tr class="row-even"><td>433.milc</td>
+<td>616.00</td>
+<td>627.00</td>
+<td>1.02</td>
+<td>627.00</td>
+<td>1.02</td>
+<td>1.00</td>
+</tr>
+<tr class="row-odd"><td>444.namd</td>
+<td>602.00</td>
+<td>601.00</td>
+<td>1.00</td>
+<td>654.00</td>
+<td>1.09</td>
+<td>1.09</td>
+</tr>
+<tr class="row-even"><td>447.dealII</td>
+<td>630.00</td>
+<td>634.00</td>
+<td>1.01</td>
+<td>653.00</td>
+<td>1.04</td>
+<td>1.03</td>
+</tr>
+<tr class="row-odd"><td>450.soplex</td>
+<td>365.00</td>
+<td>368.00</td>
+<td>1.01</td>
+<td>395.00</td>
+<td>1.08</td>
+<td>1.07</td>
+</tr>
+<tr class="row-even"><td>453.povray</td>
+<td>427.00</td>
+<td>434.00</td>
+<td>1.02</td>
+<td>495.00</td>
+<td>1.16</td>
+<td>1.14</td>
+</tr>
+<tr class="row-odd"><td>470.lbm</td>
+<td>357.00</td>
+<td>375.00</td>
+<td>1.05</td>
+<td>370.00</td>
+<td>1.04</td>
+<td>0.99</td>
+</tr>
+<tr class="row-even"><td>482.sphinx3</td>
+<td>927.00</td>
+<td>928.00</td>
+<td>1.00</td>
+<td>1000.00</td>
+<td>1.08</td>
+<td>1.08</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="why-another-coverage">
+<h2><a class="toc-backref" href="#id18">Why another coverage?</a><a class="headerlink" href="#why-another-coverage" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt>Why did we implement yet another code coverage?</dt>
+<dd><ul class="first last simple">
+<li>We needed something that is lightning fast, plays well with
+AddressSanitizer, and does not significantly increase the binary size.</li>
+<li>Traditional coverage implementations based in global counters
+<a class="reference external" href="https://groups.google.com/forum/#!topic/llvm-dev/cDqYgnxNEhY">suffer from contention on counters</a>.</li>
+</ul>
+</dd>
+</dl>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="LeakSanitizer.html">LeakSanitizer</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="SanitizerStats.html">SanitizerStats</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/SanitizerSpecialCaseList.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/SanitizerSpecialCaseList.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/SanitizerSpecialCaseList.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/SanitizerSpecialCaseList.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,149 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Sanitizer special case list — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="Control Flow Integrity" href="ControlFlowIntegrity.html" />
+    <link rel="prev" title="SanitizerStats" href="SanitizerStats.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>Sanitizer special case list</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="SanitizerStats.html">SanitizerStats</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ControlFlowIntegrity.html">Control Flow Integrity</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="sanitizer-special-case-list">
+<h1>Sanitizer special case list<a class="headerlink" href="#sanitizer-special-case-list" 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="#goal-and-usage" id="id2">Goal and usage</a></li>
+<li><a class="reference internal" href="#example" id="id3">Example</a></li>
+<li><a class="reference internal" href="#format" id="id4">Format</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>This document describes the way to disable or alter the behavior of
+sanitizer tools for certain source-level entities by providing a special
+file at compile-time.</p>
+</div>
+<div class="section" id="goal-and-usage">
+<h2><a class="toc-backref" href="#id2">Goal and usage</a><a class="headerlink" href="#goal-and-usage" title="Permalink to this headline">¶</a></h2>
+<p>User of sanitizer tools, such as <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>, <a class="reference internal" href="ThreadSanitizer.html"><em>ThreadSanitizer</em></a>
+or <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a> may want to disable or alter some checks for
+certain source-level entities to:</p>
+<ul class="simple">
+<li>speedup hot function, which is known to be correct;</li>
+<li>ignore a function that does some low-level magic (e.g. walks through the
+thread stack, bypassing the frame boundaries);</li>
+<li>ignore a known problem.</li>
+</ul>
+<p>To achieve this, user may create a file listing the entities they want to
+ignore, and pass it to clang at compile-time using
+<tt class="docutils literal"><span class="pre">-fsanitize-blacklist</span></tt> flag. See <a class="reference internal" href="UsersManual.html"><em>Clang Compiler User’s Manual</em></a> for details.</p>
+</div>
+<div class="section" id="example">
+<h2><a class="toc-backref" href="#id3">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>cat foo.c
+<span class="c">#include <stdlib.h></span>
+void bad_foo<span class="o">()</span> <span class="o">{</span>
+  int *a <span class="o">=</span> <span class="o">(</span>int*<span class="o">)</span>malloc<span class="o">(</span>40<span class="o">)</span>;
+  a<span class="o">[</span>10<span class="o">]</span> <span class="o">=</span> 1;
+<span class="o">}</span>
+int main<span class="o">()</span> <span class="o">{</span> bad_foo<span class="o">()</span>; <span class="o">}</span>
+<span class="nv">$ </span>cat blacklist.txt
+<span class="c"># Ignore reports from bad_foo function.</span>
+fun:bad_foo
+<span class="nv">$ </span>clang -fsanitize<span class="o">=</span>address foo.c ; ./a.out
+<span class="c"># AddressSanitizer prints an error report.</span>
+<span class="nv">$ </span>clang -fsanitize<span class="o">=</span>address -fsanitize-blacklist<span class="o">=</span>blacklist.txt foo.c ; ./a.out
+<span class="c"># No error report here.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="format">
+<h2><a class="toc-backref" href="#id4">Format</a><a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h2>
+<p>Each line contains an entity type, followed by a colon and a regular
+expression, specifying the names of the entities, optionally followed by
+an equals sign and a tool-specific category. Empty lines and lines starting
+with “#” are ignored. The meanining of <tt class="docutils literal"><span class="pre">*</span></tt> in regular expression for entity
+names is different - it is treated as in shell wildcarding. Two generic
+entity types are <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt>, which allow user to add, respectively,
+source files and functions to special case list. Some sanitizer tools may
+introduce custom entity types - refer to tool-specific docs.</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Lines starting with # are ignored.</span>
+<span class="c"># Turn off checks for the source file (use absolute path or path relative</span>
+<span class="c"># to the current working directory):</span>
+src:/path/to/source/file.c
+<span class="c"># Turn off checks for a particular functions (use mangled names):</span>
+fun:MyFooBar
+fun:_Z8MyFooBarv
+<span class="c"># Extended regular expressions are supported:</span>
+fun:bad_<span class="o">(</span>foo|bar<span class="o">)</span>
+src:bad_source<span class="o">[</span>1-9<span class="o">]</span>.c
+<span class="c"># Shell like usage of * is supported (* is treated as .*):</span>
+src:bad/sources/*
+fun:*BadFunction*
+<span class="c"># Specific sanitizer tools may introduce categories.</span>
+src:/special/path/*<span class="o">=</span>special_sources
+</pre></div>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="SanitizerStats.html">SanitizerStats</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="ControlFlowIntegrity.html">Control Flow Integrity</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/SanitizerStats.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/SanitizerStats.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/SanitizerStats.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/SanitizerStats.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,130 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>SanitizerStats — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="Sanitizer special case list" href="SanitizerSpecialCaseList.html" />
+    <link rel="prev" title="SanitizerCoverage" href="SanitizerCoverage.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>SanitizerStats</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="SanitizerCoverage.html">SanitizerCoverage</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="SanitizerSpecialCaseList.html">Sanitizer special case list</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="sanitizerstats">
+<h1>SanitizerStats<a class="headerlink" href="#sanitizerstats" 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-and-run" id="id2">How to build and run</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>The sanitizers support a simple mechanism for gathering profiling statistics
+to help understand the overhead associated with sanitizers.</p>
+</div>
+<div class="section" id="how-to-build-and-run">
+<h2><a class="toc-backref" href="#id2">How to build and run</a><a class="headerlink" href="#how-to-build-and-run" title="Permalink to this headline">¶</a></h2>
+<p>SanitizerStats can currently only be used with <a class="reference internal" href="ControlFlowIntegrity.html"><em>Control Flow Integrity</em></a>.
+In addition to <tt class="docutils literal"><span class="pre">-fsanitize=cfi*</span></tt>, pass the <tt class="docutils literal"><span class="pre">-fsanitize-stats</span></tt> flag.
+This will cause the program to count the number of times that each control
+flow integrity check in the program fires.</p>
+<p>At run time, set the <tt class="docutils literal"><span class="pre">SANITIZER_STATS_PATH</span></tt> environment variable to direct
+statistics output to a file. The file will be written on process exit.
+The following substitutions will be applied to the environment variable:</p>
+<blockquote>
+<div><ul class="simple">
+<li><tt class="docutils literal"><span class="pre">%b</span></tt> – The executable basename.</li>
+<li><tt class="docutils literal"><span class="pre">%p</span></tt> – The process ID.</li>
+</ul>
+</div></blockquote>
+<p>You can also send the <tt class="docutils literal"><span class="pre">SIGUSR2</span></tt> signal to a process to make it write
+sanitizer statistics immediately.</p>
+<p>The <tt class="docutils literal"><span class="pre">sanstats</span></tt> program can be used to dump statistics. It takes as a
+command line argument the path to a statistics file produced by a program
+compiled with <tt class="docutils literal"><span class="pre">-fsanitize-stats</span></tt>.</p>
+<p>The output of <tt class="docutils literal"><span class="pre">sanstats</span></tt> is in four columns, separated by spaces. The first
+column is the file and line number of the call site. The second column is
+the function name. The third column is the type of statistic gathered (in
+this case, the type of control flow integrity check). The fourth column is
+the call count.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat -n vcall.cc
+<span class="go">     1 struct A {</span>
+<span class="go">     2   virtual void f() {}</span>
+<span class="go">     3 };</span>
+<span class="go">     4</span>
+<span class="go">     5 __attribute__((noinline)) void g(A *a) {</span>
+<span class="go">     6   a->f();</span>
+<span class="go">     7 }</span>
+<span class="go">     8</span>
+<span class="go">     9 int main() {</span>
+<span class="go">    10   A a;</span>
+<span class="go">    11   g(&a);</span>
+<span class="go">    12 }</span>
+<span class="gp">$</span> clang++ -fsanitize<span class="o">=</span>cfi -flto -fuse-ld<span class="o">=</span>gold vcall.cc -fsanitize-stats -g
+<span class="gp">$</span> <span class="nv">SANITIZER_STATS_PATH</span><span class="o">=</span>a.stats ./a.out
+<span class="gp">$</span> sanstats a.stats
+<span class="go">vcall.cc:6 _Z1gP1A cfi-vcall 1</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="SanitizerCoverage.html">SanitizerCoverage</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="SanitizerSpecialCaseList.html">Sanitizer special case list</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/SourceBasedCodeCoverage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/SourceBasedCodeCoverage.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/SourceBasedCodeCoverage.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/SourceBasedCodeCoverage.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,290 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Source-based Code Coverage — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="Modules" href="Modules.html" />
+    <link rel="prev" title="SafeStack" href="SafeStack.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>Source-based Code Coverage</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="SafeStack.html">SafeStack</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Modules.html">Modules</a>  Â»
+        </p>
+
+      </div>
+      <div class="content">
+        
+        
+  <div class="section" id="source-based-code-coverage">
+<h1>Source-based Code Coverage<a class="headerlink" href="#source-based-code-coverage" 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="#the-code-coverage-workflow" id="id2">The code coverage workflow</a></li>
+<li><a class="reference internal" href="#compiling-with-coverage-enabled" id="id3">Compiling with coverage enabled</a></li>
+<li><a class="reference internal" href="#running-the-instrumented-program" id="id4">Running the instrumented program</a></li>
+<li><a class="reference internal" href="#creating-coverage-reports" id="id5">Creating coverage reports</a></li>
+<li><a class="reference internal" href="#format-compatibility-guarantees" id="id6">Format compatibility guarantees</a></li>
+<li><a class="reference internal" href="#using-the-profiling-runtime-without-static-initializers" id="id7">Using the profiling runtime without static initializers</a></li>
+<li><a class="reference internal" href="#drawbacks-and-limitations" id="id8">Drawbacks and limitations</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>This document explains how to use clang’s source-based code coverage feature.
+It’s called “source-based” because it operates on AST and preprocessor
+information directly. This allows it to generate very precise coverage data.</p>
+<p>Clang ships two other code coverage implementations:</p>
+<ul class="simple">
+<li><a class="reference internal" href="SanitizerCoverage.html"><em>SanitizerCoverage</em></a> - A low-overhead tool meant for use alongside the
+various sanitizers. It can provide up to edge-level coverage.</li>
+<li>gcov - A GCC-compatible coverage implementation which operates on DebugInfo.</li>
+</ul>
+<p>From this point onwards “code coverage” will refer to the source-based kind.</p>
+</div>
+<div class="section" id="the-code-coverage-workflow">
+<h2><a class="toc-backref" href="#id2">The code coverage workflow</a><a class="headerlink" href="#the-code-coverage-workflow" title="Permalink to this headline">¶</a></h2>
+<p>The code coverage workflow consists of three main steps:</p>
+<ul class="simple">
+<li>Compiling with coverage enabled.</li>
+<li>Running the instrumented program.</li>
+<li>Creating coverage reports.</li>
+</ul>
+<p>The next few sections work through a complete, copy-‘n-paste friendly example
+based on this program:</p>
+<div class="highlight-cpp"><div class="highlight"><pre><span class="o">%</span> <span class="n">cat</span> <span class="o"><<</span><span class="n">EOF</span> <span class="o">></span> <span class="n">foo</span><span class="p">.</span><span class="n">cc</span>
+<span class="cp">#define BAR(x) ((x) || (x))</span>
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="n">T</span> <span class="n">x</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">I</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">I</span> <span class="o"><</span> <span class="mi">10</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span> <span class="n">BAR</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">int</span> <span class="n">main</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">foo</span><span class="o"><</span><span class="kt">int</span><span class="o">></span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+  <span class="n">foo</span><span class="o"><</span><span class="kt">float</span><span class="o">></span><span class="p">(</span><span class="mi">0</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="n">EOF</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="compiling-with-coverage-enabled">
+<h2><a class="toc-backref" href="#id3">Compiling with coverage enabled</a><a class="headerlink" href="#compiling-with-coverage-enabled" title="Permalink to this headline">¶</a></h2>
+<p>To compile code with coverage enabled, pass <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span>
+<span class="pre">-fcoverage-mapping</span></tt> to the compiler:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 1: Compile with coverage enabled.
+<span class="gp">%</span> clang++ -fprofile-instr-generate -fcoverage-mapping foo.cc -o foo
+</pre></div>
+</div>
+<p>Note that linking together code with and without coverage instrumentation is
+supported: any uninstrumented code simply won’t be accounted for.</p>
+</div>
+<div class="section" id="running-the-instrumented-program">
+<h2><a class="toc-backref" href="#id4">Running the instrumented program</a><a class="headerlink" href="#running-the-instrumented-program" title="Permalink to this headline">¶</a></h2>
+<p>The next step is to run the instrumented program. When the program exits it
+will write a <strong>raw profile</strong> to the path specified by the <tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt>
+environment variable. If that variable does not exist, the profile is written
+to <tt class="docutils literal"><span class="pre">default.profraw</span></tt> in the current directory of the program. If
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> contains a path to a non-existent directory, the missing
+directory structure will be created.  Additionally, the following special
+<strong>pattern strings</strong> are rewritten:</p>
+<ul class="simple">
+<li>“%p” expands out to the process ID.</li>
+<li>“%h” expands out to the hostname of the machine running the program.</li>
+<li>“%Nm” expands out to the instrumented binary’s signature. When this pattern
+is specified, the runtime creates a pool of N raw profiles which are used for
+on-line profile merging. The runtime takes care of selecting a raw profile
+from the pool, locking it, and updating it before the program exits.  If N is
+not specified (i.e the pattern is “%m”), it’s assumed that <tt class="docutils literal"><span class="pre">N</span> <span class="pre">=</span> <span class="pre">1</span></tt>. N must
+be between 1 and 9. The merge pool specifier can only occur once per filename
+pattern.</li>
+</ul>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 2: Run the program.
+<span class="gp">%</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span><span class="s2">"foo.profraw"</span> ./foo
+</pre></div>
+</div>
+</div>
+<div class="section" id="creating-coverage-reports">
+<h2><a class="toc-backref" href="#id5">Creating coverage reports</a><a class="headerlink" href="#creating-coverage-reports" title="Permalink to this headline">¶</a></h2>
+<p>Raw profiles have to be <strong>indexed</strong> before they can be used to generate
+coverage reports. This is done using the “merge” tool in <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt>, so
+named because it can combine and index profiles at the same time:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 3<span class="o">(</span>a<span class="o">)</span>: Index the raw profile.
+<span class="gp">%</span> llvm-profdata merge -sparse foo.profraw -o foo.profdata
+</pre></div>
+</div>
+<p>There are multiple different ways to render coverage reports. One option is to
+generate a line-oriented report:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 3<span class="o">(</span>b<span class="o">)</span>: Create a line-oriented coverage report.
+<span class="gp">%</span> llvm-cov show ./foo -instr-profile<span class="o">=</span>foo.profdata
+</pre></div>
+</div>
+<p>To demangle any C++ identifiers in the output, use:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> llvm-cov show ./foo -instr-profile<span class="o">=</span>foo.profdata | c++filt -n
+</pre></div>
+</div>
+<p>This report includes a summary view as well as dedicated sub-views for
+templated functions and their instantiations. For our example program, we get
+distinct views for <tt class="docutils literal"><span class="pre">foo<int>(...)</span></tt> and <tt class="docutils literal"><span class="pre">foo<float>(...)</span></tt>.  If
+<tt class="docutils literal"><span class="pre">-show-line-counts-or-regions</span></tt> is enabled, <tt class="docutils literal"><span class="pre">llvm-cov</span></tt> displays sub-line
+region counts (even in macro expansions):</p>
+<div class="highlight-none"><div class="highlight"><pre>   20|    1|#define BAR(x) ((x) || (x))
+                           ^20     ^2
+    2|    2|template <typename T> void foo(T x) {
+   22|    3|  for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+                                   ^22     ^20  ^20^20
+    2|    4|}
+------------------
+| void foo<int>(int):
+|      1|    2|template <typename T> void foo(T x) {
+|     11|    3|  for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+|                                     ^11     ^10  ^10^10
+|      1|    4|}
+------------------
+| void foo<float>(int):
+|      1|    2|template <typename T> void foo(T x) {
+|     11|    3|  for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+|                                     ^11     ^10  ^10^10
+|      1|    4|}
+------------------
+</pre></div>
+</div>
+<p>It’s possible to generate a file-level summary of coverage statistics (instead
+of a line-oriented report) with:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">#</span> Step 3<span class="o">(</span>c<span class="o">)</span>: Create a coverage summary.
+<span class="gp">%</span> llvm-cov report ./foo -instr-profile<span class="o">=</span>foo.profdata
+<span class="go">Filename                    Regions    Miss   Cover Functions  Executed</span>
+<span class="go">-----------------------------------------------------------------------</span>
+<span class="go">/tmp/foo.cc                      13       0 100.00%         3   100.00%</span>
+<span class="go">-----------------------------------------------------------------------</span>
+<span class="go">TOTAL                            13       0 100.00%         3   100.00%</span>
+</pre></div>
+</div>
+<p>A few final notes:</p>
+<ul>
+<li><p class="first">The <tt class="docutils literal"><span class="pre">-sparse</span></tt> flag is optional but can result in dramatically smaller
+indexed profiles. This option should not be used if the indexed profile will
+be reused for PGO.</p>
+</li>
+<li><p class="first">Raw profiles can be discarded after they are indexed. Advanced use of the
+profile runtime library allows an instrumented program to merge profiling
+information directly into an existing raw profile on disk. The details are
+out of scope.</p>
+</li>
+<li><p class="first">The <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool can be used to merge together multiple raw or
+indexed profiles. To combine profiling data from multiple runs of a program,
+try e.g:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">%</span> llvm-profdata merge -sparse foo1.profraw foo2.profdata -o foo3.profdata
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="format-compatibility-guarantees">
+<h2><a class="toc-backref" href="#id6">Format compatibility guarantees</a><a class="headerlink" href="#format-compatibility-guarantees" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>There are no backwards or forwards compatibility guarantees for the raw
+profile format. Raw profiles may be dependent on the specific compiler
+revision used to generate them. It’s inadvisable to store raw profiles for
+long periods of time.</li>
+<li>Tools must retain <strong>backwards</strong> compatibility with indexed profile formats.
+These formats are not forwards-compatible: i.e, a tool which uses format
+version X will not be able to understand format version (X+k).</li>
+<li>There is a third format in play: the format of the coverage mappings emitted
+into instrumented binaries. Tools must retain <strong>backwards</strong> compatibility
+with these formats. These formats are not forwards-compatible.</li>
+</ul>
+</div>
+<div class="section" id="using-the-profiling-runtime-without-static-initializers">
+<h2><a class="toc-backref" href="#id7">Using the profiling runtime without static initializers</a><a class="headerlink" href="#using-the-profiling-runtime-without-static-initializers" title="Permalink to this headline">¶</a></h2>
+<p>By default the compiler runtime uses a static initializer to determine the
+profile output path and to register a writer function. To collect profiles
+without using static initializers, do this manually:</p>
+<ul class="simple">
+<li>Export a <tt class="docutils literal"><span class="pre">int</span> <span class="pre">__llvm_profile_runtime</span></tt> symbol from each instrumented shared
+library and executable. When the linker finds a definition of this symbol, it
+knows to skip loading the object which contains the profiling runtime’s
+static initializer.</li>
+<li>Forward-declare <tt class="docutils literal"><span class="pre">void</span> <span class="pre">__llvm_profile_initialize_file(void)</span></tt> and call it
+once from each instrumented executable. This function parses
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt>, sets the output path, and truncates any existing files
+at that path. To get the same behavior without truncating existing files,
+pass a filename pattern string to <tt class="docutils literal"><span class="pre">void</span> <span class="pre">__llvm_profile_set_filename(char</span>
+<span class="pre">*)</span></tt>.  These calls can be placed anywhere so long as they precede all calls
+to <tt class="docutils literal"><span class="pre">__llvm_profile_write_file</span></tt>.</li>
+<li>Forward-declare <tt class="docutils literal"><span class="pre">int</span> <span class="pre">__llvm_profile_write_file(void)</span></tt> and call it to write
+out a profile. This function returns 0 when it succeeds, and a non-zero value
+otherwise. Calling this function multiple times appends profile data to an
+existing on-disk raw profile.</li>
+</ul>
+</div>
+<div class="section" id="drawbacks-and-limitations">
+<h2><a class="toc-backref" href="#id8">Drawbacks and limitations</a><a class="headerlink" href="#drawbacks-and-limitations" title="Permalink to this headline">¶</a></h2>
+<ul>
+<li><p class="first">Code coverage does not handle unpredictable changes in control flow or stack
+unwinding in the presence of exceptions precisely. Consider the following
+function:</p>
+<div class="highlight-cpp"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">f</span><span class="p">()</span> <span class="p">{</span>
+  <span class="n">may_throw</span><span class="p">();</span>
+  <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If the call to <tt class="docutils literal"><span class="pre">may_throw()</span></tt> propagates an exception into <tt class="docutils literal"><span class="pre">f</span></tt>, the code
+coverage tool may mark the <tt class="docutils literal"><span class="pre">return</span></tt> statement as executed even though it is
+not. A call to <tt class="docutils literal"><span class="pre">longjmp()</span></tt> can have similar effects.</p>
+</li>
+</ul>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <p>
+        «  <a href="SafeStack.html">SafeStack</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="Modules.html">Modules</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/ThreadSafetyAnalysis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/ThreadSafetyAnalysis.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/ThreadSafetyAnalysis.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/ThreadSafetyAnalysis.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,914 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Thread Safety Analysis — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="AddressSanitizer" href="AddressSanitizer.html" />
+    <link rel="prev" title="Cross-compilation using Clang" href="CrossCompilation.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>Thread Safety Analysis</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="CrossCompilation.html">Cross-compilation using Clang</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. <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>,
+etc.), the programmer can (optionally) declare how access to that data is
+controlled in a multi-threaded environment.  For example, if <tt class="docutils literal"><span class="pre">foo</span></tt> is
+<em>guarded by</em> the mutex <tt class="docutils literal"><span class="pre">mu</span></tt>, then the analysis will issue a warning whenever
+a piece of code reads or writes to <tt class="docutils literal"><span class="pre">foo</span></tt> without first locking <tt class="docutils literal"><span class="pre">mu</span></tt>.
+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++"><div class="highlight"><pre><span class="cp">#include "mutex.h"</span>
+
+<span class="k">class</span> <span class="nc">BankAccount</span> <span class="p">{</span>
+<span class="nl">private:</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="nl">public:</span>
+  <span class="kt">void</span> <span class="nf">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="nf">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
+<tt class="docutils literal"><span class="pre">GUARDED_BY</span></tt> attribute declares that a thread must lock <tt class="docutils literal"><span class="pre">mu</span></tt> before it can
+read or write to <tt class="docutils literal"><span class="pre">balance</span></tt>, thus ensuring that the increment and decrement
+operations are atomic.  Similarly, <tt class="docutils literal"><span class="pre">REQUIRES</span></tt> declares that
+the calling thread must lock <tt class="docutils literal"><span class="pre">mu</span></tt> before calling <tt class="docutils literal"><span class="pre">withdrawImpl</span></tt>.
+Because the caller is assumed to have locked <tt class="docutils literal"><span class="pre">mu</span></tt>, it is safe to modify
+<tt class="docutils literal"><span class="pre">balance</span></tt> within the body of the method.</p>
+<p>The <tt class="docutils literal"><span class="pre">depositImpl()</span></tt> method does not have <tt class="docutils literal"><span class="pre">REQUIRES</span></tt>, 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 <tt class="docutils literal"><span class="pre">transferFrom()</span></tt>, because although the method
+locks <tt class="docutils literal"><span class="pre">this->mu</span></tt>, it does not lock <tt class="docutils literal"><span class="pre">b.mu</span></tt>.  The analysis understands
+that these are two separate mutexes, in two different objects.</p>
+<p>Finally, there is a warning in the <tt class="docutils literal"><span class="pre">withdraw()</span></tt> method, because it fails to
+unlock <tt class="docutils literal"><span class="pre">mu</span></tt>.  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 <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt>/<tt class="docutils literal"><span class="pre">RELEASE</span></tt>).</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 <tt class="docutils literal"><span class="pre">-Wthread-safety</span></tt> flag, e.g.</p>
+<div class="highlight-bash"><div class="highlight"><pre>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"><em>mutex.h</em></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 <tt class="docutils literal"><span class="pre">mu</span></tt> is a mutex, then calling <tt class="docutils literal"><span class="pre">mu.Lock()</span></tt> causes the calling thread
+to acquire the capability to access data that is protected by <tt class="docutils literal"><span class="pre">mu</span></tt>. Similarly,
+calling <tt class="docutils literal"><span class="pre">mu.Unlock()</span></tt> 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"><em>mutex.h</em></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><tt class="docutils literal"><span class="pre">GUARDED_BY</span></tt> 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><tt class="docutils literal"><span class="pre">PT_GUARDED_BY</span></tt> 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++"><div class="highlight"><pre><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>: <tt class="docutils literal"><span class="pre">EXCLUSIVE_LOCKS_REQUIRED</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_LOCKS_REQUIRED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">REQUIRES</span></tt> 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><tt class="docutils literal"><span class="pre">REQUIRES_SHARED</span></tt> is similar, but requires only shared access.</p>
+<div class="highlight-c++"><div class="highlight"><pre><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>: <tt class="docutils literal"><span class="pre">EXCLUSIVE_LOCK_FUNCTION</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_LOCK_FUNCTION</span></tt>,
+<tt class="docutils literal"><span class="pre">UNLOCK_FUNCTION</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">ACQUIRE</span></tt> 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.  <tt class="docutils literal"><span class="pre">ACQUIRE_SHARED</span></tt> is similar.</p>
+<p><tt class="docutils literal"><span class="pre">RELEASE</span></tt> and <tt class="docutils literal"><span class="pre">RELEASE_SHARED</span></tt> 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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt> or <tt class="docutils literal"><span class="pre">RELEASE</span></tt>, then the argument is
+assumed to be <tt class="docutils literal"><span class="pre">this</span></tt>, 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++"><div class="highlight"><pre><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="nl">private:</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="nl">public:</span>
+  <span class="c1">// Hide mu from public interface.</span>
+  <span class="kt">void</span> <span class="nf">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="nf">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>: <tt class="docutils literal"><span class="pre">LOCKS_EXCLUDED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">EXCLUDES</span></tt> 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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">REQUIRES</span></tt>, <tt class="docutils literal"><span class="pre">EXCLUDES</span></tt> 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"><em>Negative Capabilities</em></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><tt class="docutils literal"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></tt> 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"><em>Known Limitations</em></a>, below.</p>
+<div class="highlight-c++"><div class="highlight"><pre><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="n">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 <tt class="docutils literal"><span class="pre">.cc</span></tt> or <tt class="docutils literal"><span class="pre">.cpp</span></tt> 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>: <tt class="docutils literal"><span class="pre">LOCK_RETURNED</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">RETURN_CAPABILITY</span></tt> 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++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="nl">private:</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="nl">public:</span>
+  <span class="n">Mutex</span><span class="o">*</span> <span class="nf">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="nf">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><tt class="docutils literal"><span class="pre">ACQUIRED_BEFORE</span></tt> and <tt class="docutils literal"><span class="pre">ACQUIRED_AFTER</span></tt> 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++"><div class="highlight"><pre><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>: <tt class="docutils literal"><span class="pre">LOCKABLE</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">CAPABILITY</span></tt> 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. <tt class="docutils literal"><span class="pre">"mutex"</span></tt>.  See the <tt class="docutils literal"><span class="pre">Container</span></tt> example
+given above, or the <tt class="docutils literal"><span class="pre">Mutex</span></tt> class in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></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>: <tt class="docutils literal"><span class="pre">SCOPED_LOCKABLE</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">SCOPED_CAPABILITY</span></tt> 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
+<tt class="docutils literal"><span class="pre">MutexLocker</span></tt> class in <a class="reference internal" href="#mutexheader"><em>mutex.h</em></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> <tt class="docutils literal"><span class="pre">EXCLUSIVE_TRYLOCK_FUNCTION</span></tt>, <tt class="docutils literal"><span class="pre">SHARED_TRYLOCK_FUNCTION</span></tt></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 <tt class="docutils literal"><span class="pre">true</span></tt> or <tt class="docutils literal"><span class="pre">false</span></tt>, to specify which return value
+indicates success, and the remaining arguments are interpreted in the same way
+as <tt class="docutils literal"><span class="pre">ACQUIRE</span></tt>.  See <a class="reference internal" href="#mutexheader"><em>mutex.h</em></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>  <tt class="docutils literal"><span class="pre">ASSERT_EXCLUSIVE_LOCK</span></tt>, <tt class="docutils literal"><span class="pre">ASSERT_SHARED_LOCK</span></tt></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"><em>mutex.h</em></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>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety</span></tt>:  Umbrella flag which turns on the following three:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-attributes</span></tt>: Sanity checks on attribute syntax.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-analysis</span></tt>: The core analysis.</p>
+</li>
+<li><dl class="first docutils">
+<dt><tt class="docutils literal"><span class="pre">-Wthread-safety-precise</span></tt>: Requires that mutex expressions match precisely.</dt>
+<dd><p class="first last">This warning can be disabled for code which has a lot of aliases.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-Wthread-safety-reference</span></tt>: Checks when guarded members are passed by reference.</p>
+</li>
+</ul>
+</li>
+</ul>
+<p><a class="reference internal" href="#negative"><em>Negative Capabilities</em></a> are an experimental feature, which are enabled with:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-Wthread-safety-negative</span></tt>:  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><tt class="docutils literal"><span class="pre">-Wthread-safety-beta</span></tt>:  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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">!</span></tt> operator, to indicate that a capability
+should <em>not</em> be held.</p>
+<p>For example, using <tt class="docutils literal"><span class="pre">REQUIRES(!mu)</span></tt> instead of <tt class="docutils literal"><span class="pre">EXCLUDES(mu)</span></tt> will produce
+the appropriate warnings:</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">-Wthread-safety-negative</span></tt>.</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"><em>No conditionally held locks.</em></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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">mu</span></tt>
+is a private member of <tt class="docutils literal"><span class="pre">c</span></tt>, then it is an error to write <tt class="docutils literal"><span class="pre">c.mu</span></tt> in an
+attribute.</p>
+<p>One workaround is to (ab)use the <tt class="docutils literal"><span class="pre">RETURN_CAPABILITY</span></tt> 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++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyClass</span> <span class="p">{</span>
+<span class="nl">private:</span>
+  <span class="n">Mutex</span> <span class="n">mu</span><span class="p">;</span>
+
+<span class="nl">public:</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="nf">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="nf">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, <tt class="docutils literal"><span class="pre">doSomethingTwice()</span></tt> is an external routine that
+requires <tt class="docutils literal"><span class="pre">c.mu</span></tt> to be locked, which cannot be declared directly because <tt class="docutils literal"><span class="pre">mu</span></tt>
+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 <tt class="docutils literal"><span class="pre">getMu()</span></tt>
+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++"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">NO_THREAD_SAFETY_ANALYSIS</span></tt>.
+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++"><div class="highlight"><pre><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="nl">public:</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 <tt class="docutils literal"><span class="pre">Autocleanup</span></tt> calls <tt class="docutils literal"><span class="pre">mu.Unlock()</span></tt>, 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++"><div class="highlight"><pre><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="nl">public:</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"><em>mutex.h</em></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 <tt class="docutils literal"><span class="pre">mutex.h</span></tt> as an example;
+these methods should be filled in to call the appropriate underlying
+implementation.</p>
+<div class="highlight-c++"><div class="highlight"><pre><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 THREAD_ANNOTATION_ATTRIBUTE__(x)   __attribute__((x))</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="nl">public:</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="nf">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="nf">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="nf">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="nf">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="nf">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="nf">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="nf">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="nl">private:</span>
+  <span class="n">Mutex</span><span class="o">*</span> <span class="n">mut</span><span class="p">;</span>
+
+<span class="nl">public:</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)</span>
+
+<span class="c1">// Deprecated.</span>
+<span class="cp">#define GUARDED_VAR \</span>
+<span class="cp">  THREAD_ANNOTATION_ATTRIBUTE__(guarded)</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">
+      
+        <p>
+        «  <a href="CrossCompilation.html">Cross-compilation using Clang</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="AddressSanitizer.html">AddressSanitizer</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/ThreadSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/ThreadSanitizer.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/ThreadSanitizer.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/ThreadSanitizer.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,192 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>ThreadSanitizer — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="MemorySanitizer" href="MemorySanitizer.html" />
+    <link rel="prev" title="AddressSanitizer" href="AddressSanitizer.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>ThreadSanitizer</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <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="http://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 Linux x86_64 (tested on Ubuntu 12.04).
+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 <tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>.  To get a
+reasonable performance add <tt class="docutils literal"><span class="pre">-O1</span></tt> or higher.  Use <tt class="docutils literal"><span class="pre">-g</span></tt> to get file names
+and line numbers in the warning messages.</p>
+<p>Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><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
+<tt class="docutils literal"><span class="pre">addr2line</span></tt> process (this will be fixed in future).</p>
+<div class="highlight-bash"><div class="highlight"><pre>% ./a.out
+WARNING: ThreadSanitizer: data race <span class="o">(</span><span class="nv">pid</span><span class="o">=</span>19219<span class="o">)</span>
+  Write of size 4 at 0x7fcf47b21bc0 by thread T1:
+    <span class="c">#0 Thread1 tiny_race.c:4 (exe+0x00000000a360)</span>
+
+  Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
+    <span class="c">#0 main tiny_race.c:10 (exe+0x00000000a3b4)</span>
+
+  Thread T1 <span class="o">(</span>running<span class="o">)</span> created at:
+    <span class="c">#0 pthread_create tsan_interceptors.cc:705 (exe+0x00000000c790)</span>
+    <span class="c">#1 main tiny_race.c:9 (exe+0x00000000a3a4)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="has-feature-thread-sanitizer">
+<h2><tt class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></tt><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"><em>__has_feature</em></a> can be used for
+this purpose.</p>
+<div class="highlight-c"><div class="highlight"><pre><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><tt class="docutils literal"><span class="pre">__attribute__((no_sanitize_thread))</span></tt><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 <cite>no_sanitize_thread</cite> 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 <tt class="docutils literal"><span class="pre">__has_feature(thread_sanitizer)</span></tt>.</p>
+</div>
+<div class="section" id="blacklist">
+<h2>Blacklist<a class="headerlink" href="#blacklist" title="Permalink to this headline">¶</a></h2>
+<p>ThreadSanitizer supports <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></a>, that can be used to suppress data race reports
+in the specified source files or functions. Unlike functions marked with
+<cite>no_sanitize_thread</cite> 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 <tt class="docutils literal"><span class="pre">ulimit</span></tt> 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
+<tt class="docutils literal"><span class="pre">fsanitize=thread</span></tt> flag will cause Clang to act as though the <tt class="docutils literal"><span class="pre">-fPIE</span></tt>
+flag had been supplied if compiling without <tt class="docutils literal"><span class="pre">-fPIC</span></tt>, and as though the
+<tt class="docutils literal"><span class="pre">-pie</span></tt> 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 <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-tsan</span></tt> 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">
+      
+        <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">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/Tooling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/Tooling.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/Tooling.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/Tooling.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,162 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Choosing the Right Interface for Your Application — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.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"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>Choosing the Right Interface for Your Application</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <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="http://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"><em>Clang Plugins</em></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"><em>LibTooling</em></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"><em>Clang tools</em></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">
+      
+        <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">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/UndefinedBehaviorSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/UndefinedBehaviorSanitizer.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/UndefinedBehaviorSanitizer.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/UndefinedBehaviorSanitizer.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,333 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>UndefinedBehaviorSanitizer — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="DataFlowSanitizer" href="DataFlowSanitizer.html" />
+    <link rel="prev" title="MemorySanitizer" href="MemorySanitizer.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>UndefinedBehaviorSanitizer</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <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="#availablle-checks" id="id4">Availablle checks</a></li>
+<li><a class="reference internal" href="#stack-traces-and-report-symbolization" id="id5">Stack traces and report symbolization</a></li>
+<li><a class="reference internal" href="#issue-suppression" id="id6">Issue Suppression</a><ul>
+<li><a class="reference internal" href="#disabling-instrumentation-with-attribute-no-sanitize-undefined" id="id7">Disabling Instrumentation with <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></tt></a></li>
+<li><a class="reference internal" href="#suppressing-errors-in-recompiled-code-blacklist" id="id8">Suppressing Errors in Recompiled Code (Blacklist)</a></li>
+<li><a class="reference internal" href="#runtime-suppressions" id="id9">Runtime suppressions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#supported-platforms" id="id10">Supported Platforms</a></li>
+<li><a class="reference internal" href="#current-status" id="id11">Current Status</a></li>
+<li><a class="reference internal" href="#additional-configuration" id="id12">Additional Configuration</a><ul>
+<li><a class="reference internal" href="#example" id="id13">Example</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#more-information" id="id14">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"><em>checks</em></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="http://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 <tt class="docutils literal"><span class="pre">clang++</span></tt> to compile and link your program with <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>
+flag. Make sure to use <tt class="docutils literal"><span class="pre">clang++</span></tt> (not <tt class="docutils literal"><span class="pre">ld</span></tt>) as a linker, so that your
+executable is linked with proper UBSan runtime libraries. You can use <tt class="docutils literal"><span class="pre">clang</span></tt>
+instead of <tt class="docutils literal"><span class="pre">clang++</span></tt> if you’re compiling/linking C code.</p>
+<div class="highlight-console"><div class="highlight"><pre><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"><em>checks</em></a> offered by UBSan,
+and define the desired behavior for each kind of check:</p>
+<ul class="simple">
+<li>print a verbose error report and continue execution (default);</li>
+<li>print a verbose error report and exit the program;</li>
+<li>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"><div class="highlight"><pre><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="availablle-checks">
+<span id="ubsan-checks"></span><h2><a class="toc-backref" href="#id4">Availablle checks</a><a class="headerlink" href="#availablle-checks" title="Permalink to this headline">¶</a></h2>
+<p>Available checks are:</p>
+<blockquote>
+<div><ul class="simple">
+<li><tt class="docutils literal"><span class="pre">-fsanitize=alignment</span></tt>: Use of a misaligned pointer or creation
+of a misaligned reference.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=bool</span></tt>: Load of a <tt class="docutils literal"><span class="pre">bool</span></tt> value which is neither
+<tt class="docutils literal"><span class="pre">true</span></tt> nor <tt class="docutils literal"><span class="pre">false</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=bounds</span></tt>: Out of bounds array indexing, in cases
+where the array bound can be statically determined.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=enum</span></tt>: Load of a value of an enumerated type which
+is not in the range of representable values for that enumerated
+type.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=float-cast-overflow</span></tt>: Conversion to, from, or
+between floating-point types which would overflow the
+destination.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=float-divide-by-zero</span></tt>: Floating point division by
+zero.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=function</span></tt>: Indirect call of a function through a
+function pointer of the wrong type (Linux, C++ and x86/x86_64 only).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=integer-divide-by-zero</span></tt>: Integer division by zero.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=nonnull-attribute</span></tt>: Passing null pointer as a function
+parameter which is declared to never be null.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=null</span></tt>: Use of a null pointer or creation of a null
+reference.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=object-size</span></tt>: 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
+<tt class="docutils literal"><span class="pre">__builtin_object_size</span></tt>, and consequently may be able to detect more
+problems at higher optimization levels.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=return</span></tt>: In C++, reaching the end of a
+value-returning function without returning a value.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=returns-nonnull-attribute</span></tt>: Returning null pointer
+from a function which is declared to never return null.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=shift</span></tt>: 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 <tt class="docutils literal"><span class="pre">-fsanitize=shift-base</span></tt> or
+<tt class="docutils literal"><span class="pre">-fsanitize=shift-exponent</span></tt> to check only left-hand side or
+right-hand side of shift operation, respectively.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=signed-integer-overflow</span></tt>: Signed integer overflow,
+including all the checks added by <tt class="docutils literal"><span class="pre">-ftrapv</span></tt>, and checking for
+overflow in signed division (<tt class="docutils literal"><span class="pre">INT_MIN</span> <span class="pre">/</span> <span class="pre">-1</span></tt>).</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=unreachable</span></tt>: If control flow reaches
+<tt class="docutils literal"><span class="pre">__builtin_unreachable</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=unsigned-integer-overflow</span></tt>: Unsigned integer
+overflows.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=vla-bound</span></tt>: A variable-length array whose bound
+does not evaluate to a positive value.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=vptr</span></tt>: 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 <tt class="docutils literal"><span class="pre">-fno-rtti</span></tt>. Link must
+be performed by <tt class="docutils literal"><span class="pre">clang++</span></tt>, not <tt class="docutils literal"><span class="pre">clang</span></tt>, 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><tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>: All of the checks listed above other than
+<tt class="docutils literal"><span class="pre">unsigned-integer-overflow</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=undefined-trap</span></tt>: Deprecated alias of
+<tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=integer</span></tt>: Checks for undefined or suspicious integer
+behavior (e.g. unsigned integer overflow).</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section" id="stack-traces-and-report-symbolization">
+<h2><a class="toc-backref" href="#id5">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 <tt class="docutils literal"><span class="pre">-g</span></tt> and <tt class="docutils literal"><span class="pre">-fno-omit-frame-pointer</span></tt> to get proper debug
+information in your binary.</li>
+<li>Run your program with environment variable
+<tt class="docutils literal"><span class="pre">UBSAN_OPTIONS=print_stacktrace=1</span></tt>.</li>
+<li>Make sure <tt class="docutils literal"><span class="pre">llvm-symbolizer</span></tt> binary is in <tt class="docutils literal"><span class="pre">PATH</span></tt>.</li>
+</ol>
+</div>
+<div class="section" id="issue-suppression">
+<h2><a class="toc-backref" href="#id6">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="#id7">Disabling Instrumentation with <tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></tt></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
+<tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("undefined")))</span></tt>. You can use all values of
+<tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> flag in this attribute, e.g. if your function deliberately
+contains possible signed integer overflow, you can use
+<tt class="docutils literal"><span class="pre">__attribute__((no_sanitize("signed-integer-overflow")))</span></tt>.</p>
+<p>This attribute may not be
+supported by other compilers, so consider using it together with
+<tt class="docutils literal"><span class="pre">#if</span> <span class="pre">defined(__clang__)</span></tt>.</p>
+</div>
+<div class="section" id="suppressing-errors-in-recompiled-code-blacklist">
+<h3><a class="toc-backref" href="#id8">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 <tt class="docutils literal"><span class="pre">src</span></tt> and <tt class="docutils literal"><span class="pre">fun</span></tt> entity types in
+<a class="reference internal" href="SanitizerSpecialCaseList.html"><em>Sanitizer special case list</em></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="#id9">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 <tt class="docutils literal"><span class="pre">UBSAN_OPTIONS</span></tt> environment variable.</p>
+<div class="highlight-bash"><div class="highlight"><pre><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"><em>check</em></a> you are suppressing and the
+bug location. For example:</p>
+<div class="highlight-bash"><div class="highlight"><pre>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
+<tt class="docutils literal"><span class="pre">-fsanitize-recover=signed-integer-overflow,alignment,vptr</span></tt>, although
+most of UBSan checks are recoverable by default.</li>
+<li>Check groups (like <tt class="docutils literal"><span class="pre">undefined</span></tt>) 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="#id10">Supported Platforms</a><a class="headerlink" href="#supported-platforms" title="Permalink to this headline">¶</a></h2>
+<p>UndefinedBehaviorSanitizer is supported on the following OS:</p>
+<ul class="simple">
+<li>Android</li>
+<li>Linux</li>
+<li>FreeBSD</li>
+<li>OS X 10.6 onwards</li>
+</ul>
+<p>and for the following architectures:</p>
+<ul class="simple">
+<li>i386/x86_64</li>
+<li>ARM</li>
+<li>AArch64</li>
+<li>PowerPC64</li>
+<li>MIPS/MIPS64</li>
+</ul>
+</div>
+<div class="section" id="current-status">
+<h2><a class="toc-backref" href="#id11">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
+<tt class="docutils literal"><span class="pre">check-ubsan</span></tt> command.</p>
+</div>
+<div class="section" id="additional-configuration">
+<h2><a class="toc-backref" href="#id12">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
+<tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=N</span></tt> can be used to trim this
+information. If <tt class="docutils literal"><span class="pre">N</span></tt> is positive, file information emitted by
+UndefinedBehaviorSanitizer will drop the first <tt class="docutils literal"><span class="pre">N</span></tt> components from the file
+path. If <tt class="docutils literal"><span class="pre">N</span></tt> is negative, the last <tt class="docutils literal"><span class="pre">N</span></tt> components will be kept.</p>
+<div class="section" id="example">
+<h3><a class="toc-backref" href="#id13">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
+<p>For a file called <tt class="docutils literal"><span class="pre">/code/library/file.cpp</span></tt>, here is what would be emitted:
+* Default (No flag, or <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=0</span></tt>): <tt class="docutils literal"><span class="pre">/code/library/file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=1</span></tt>: <tt class="docutils literal"><span class="pre">code/library/file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=2</span></tt>: <tt class="docutils literal"><span class="pre">library/file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=-1</span></tt>: <tt class="docutils literal"><span class="pre">file.cpp</span></tt>
+* <tt class="docutils literal"><span class="pre">-fsanitize-undefined-strip-path-components=-2</span></tt>: <tt class="docutils literal"><span class="pre">library/file.cpp</span></tt></p>
+</div>
+</div>
+<div class="section" id="more-information">
+<h2><a class="toc-backref" href="#id14">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="http://blog.regehr.org/archives/213">A Guide to Undefined Behavior in C and C++</a></li>
+</ul>
+</div>
+</div>
+
+
+      </div>
+      <div class="bottomnav">
+      
+        <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">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/UsersManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/UsersManual.html?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/UsersManual.html (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/UsersManual.html Fri Sep  2 10:56:46 2016
@@ -0,0 +1,2221 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Clang Compiler User’s Manual — Clang 3.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">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '3.9',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    <link rel="top" title="Clang 3.9 documentation" href="index.html" />
+    <link rel="next" title="Clang Language Extensions" href="LanguageExtensions.html" />
+    <link rel="prev" title="Clang 3.9 Release Notes" href="ReleaseNotes.html" /> 
+  </head>
+  <body>
+      <div class="header"><h1 class="heading"><a href="index.html">
+          <span>Clang 3.9 documentation</span></a></h1>
+        <h2 class="heading"><span>Clang Compiler User’s Manual</span></h2>
+      </div>
+      <div class="topnav">
+      
+        <p>
+        «  <a href="ReleaseNotes.html">Clang 3.9 Release Notes</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="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="id8">Introduction</a><ul>
+<li><a class="reference internal" href="#terminology" id="id9">Terminology</a></li>
+<li><a class="reference internal" href="#basic-usage" id="id10">Basic Usage</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#command-line-options" id="id11">Command Line Options</a><ul>
+<li><a class="reference internal" href="#options-to-control-error-and-warning-messages" id="id12">Options to Control Error and Warning Messages</a><ul>
+<li><a class="reference internal" href="#formatting-of-diagnostics" id="id13">Formatting of Diagnostics</a></li>
+<li><a class="reference internal" href="#individual-warning-groups" id="id14">Individual Warning Groups</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#options-to-control-clang-crash-diagnostics" id="id15">Options to Control Clang Crash Diagnostics</a></li>
+<li><a class="reference internal" href="#options-to-emit-optimization-reports" id="id16">Options to Emit Optimization Reports</a><ul>
+<li><a class="reference internal" href="#current-limitations" id="id17">Current limitations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#other-options" id="id18">Other Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#language-and-target-independent-features" id="id19">Language and Target-Independent Features</a><ul>
+<li><a class="reference internal" href="#controlling-errors-and-warnings" id="id20">Controlling Errors and Warnings</a><ul>
+<li><a class="reference internal" href="#controlling-how-clang-displays-diagnostics" id="id21">Controlling How Clang Displays Diagnostics</a></li>
+<li><a class="reference internal" href="#diagnostic-mappings" id="id22">Diagnostic Mappings</a></li>
+<li><a class="reference internal" href="#diagnostic-categories" id="id23">Diagnostic Categories</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-command-line-flags" id="id24">Controlling Diagnostics via Command Line Flags</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-via-pragmas" id="id25">Controlling Diagnostics via Pragmas</a></li>
+<li><a class="reference internal" href="#controlling-diagnostics-in-system-headers" id="id26">Controlling Diagnostics in System Headers</a></li>
+<li><a class="reference internal" href="#enabling-all-diagnostics" id="id27">Enabling All Diagnostics</a></li>
+<li><a class="reference internal" href="#controlling-static-analyzer-diagnostics" id="id28">Controlling Static Analyzer Diagnostics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#precompiled-headers" id="id29">Precompiled Headers</a><ul>
+<li><a class="reference internal" href="#generating-a-pch-file" id="id30">Generating a PCH File</a></li>
+<li><a class="reference internal" href="#using-a-pch-file" id="id31">Using a PCH File</a></li>
+<li><a class="reference internal" href="#relocatable-pch-files" id="id32">Relocatable PCH Files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-code-generation" id="id33">Controlling Code Generation</a></li>
+<li><a class="reference internal" href="#profile-guided-optimization" id="id34">Profile Guided Optimization</a><ul>
+<li><a class="reference internal" href="#differences-between-sampling-and-instrumentation" id="id35">Differences Between Sampling and Instrumentation</a></li>
+<li><a class="reference internal" href="#using-sampling-profilers" id="id36">Using Sampling Profilers</a><ul>
+<li><a class="reference internal" href="#sample-profile-formats" id="id37">Sample Profile Formats</a></li>
+<li><a class="reference internal" href="#sample-profile-text-format" id="id38">Sample Profile Text Format</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#profiling-with-instrumentation" id="id39">Profiling with Instrumentation</a></li>
+<li><a class="reference internal" href="#disabling-instrumentation" id="id40">Disabling Instrumentation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#controlling-debug-information" id="id41">Controlling Debug Information</a><ul>
+<li><a class="reference internal" href="#controlling-size-of-debug-information" id="id42">Controlling Size of Debug Information</a></li>
+<li><a class="reference internal" href="#controlling-debugger-tuning" id="id43">Controlling Debugger “Tuning”</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#comment-parsing-options" id="id44">Comment Parsing Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-language-features" id="id45">C Language Features</a><ul>
+<li><a class="reference internal" href="#extensions-supported-by-clang" id="id46">Extensions supported by clang</a></li>
+<li><a class="reference internal" href="#differences-between-various-standard-modes" id="id47">Differences between various standard modes</a></li>
+<li><a class="reference internal" href="#gcc-extensions-not-implemented-yet" id="id48">GCC extensions not implemented yet</a></li>
+<li><a class="reference internal" href="#intentionally-unsupported-gcc-extensions" id="id49">Intentionally unsupported GCC extensions</a></li>
+<li><a class="reference internal" href="#microsoft-extensions" id="id50">Microsoft extensions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#cxx" id="id51">C++ Language Features</a><ul>
+<li><a class="reference internal" href="#controlling-implementation-limits" id="id52">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#objective-c-language-features" id="id53">Objective-C Language Features</a></li>
+<li><a class="reference internal" href="#objcxx" id="id54">Objective-C++ Language Features</a></li>
+<li><a class="reference internal" href="#openmp-features" id="id55">OpenMP Features</a><ul>
+<li><a class="reference internal" href="#id5" id="id56">Controlling implementation limits</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-specific-features-and-limitations" id="id57">Target-Specific Features and Limitations</a><ul>
+<li><a class="reference internal" href="#cpu-architectures-features-and-limitations" id="id58">CPU Architectures Features and Limitations</a><ul>
+<li><a class="reference internal" href="#x86" id="id59">X86</a></li>
+<li><a class="reference internal" href="#arm" id="id60">ARM</a></li>
+<li><a class="reference internal" href="#powerpc" id="id61">PowerPC</a></li>
+<li><a class="reference internal" href="#other-platforms" id="id62">Other platforms</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#operating-system-features-and-limitations" id="id63">Operating System Features and Limitations</a><ul>
+<li><a class="reference internal" href="#darwin-mac-os-x" id="id64">Darwin (Mac OS X)</a></li>
+<li><a class="reference internal" href="#windows" id="id65">Windows</a><ul>
+<li><a class="reference internal" href="#cygwin" id="id66">Cygwin</a></li>
+<li><a class="reference internal" href="#mingw32" id="id67">MinGW32</a></li>
+<li><a class="reference internal" href="#mingw-w64" id="id68">MinGW-w64</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#clang-cl" id="id69">clang-cl</a><ul>
+<li><a class="reference internal" href="#id7" id="id70">Command-Line Options</a><ul>
+<li><a class="reference internal" href="#the-fallback-option" id="id71">The /fallback Option</a></li>
+</ul>
+</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>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="http://clang.llvm.org">Clang Web Site</a> or the <a class="reference external" href="http://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"><em>“Clang” CFE Internals Manual</em></a>. If you are interested in the
+<a class="reference external" href="http://clang-analyzer.llvm.org">Clang Static Analyzer</a>, please see its web
+page.</p>
+<p>Clang is designed to support the C family of programming languages,
+which includes <a class="reference internal" href="#c"><em>C</em></a>, <a class="reference internal" href="#objc"><em>Objective-C</em></a>, <a class="reference internal" href="#cxx"><em>C++</em></a>, and
+<a class="reference internal" href="#objcxx"><em>Objective-C++</em></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"><em>C Language</em></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"><em>Objective-C Language</em></a>: ObjC 1, ObjC 2, ObjC 2.1, plus
+variants depending on base language.</li>
+<li><a class="reference internal" href="#cxx"><em>C++ Language</em></a></li>
+<li><a class="reference internal" href="#objcxx"><em>Objective C++ Language</em></a></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"><em>clang-cl</em></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"><em>Target-Specific Features and
+Limitations</em></a> section for more details.</p>
+<p>The rest of the introduction introduces some basic <a class="reference internal" href="#terminology"><em>compiler
+terminology</em></a> that is used throughout this manual and
+contains a basic <a class="reference internal" href="#basicusage"><em>introduction to using Clang</em></a> as a
+command line compiler.</p>
+<div class="section" id="terminology">
+<span id="id1"></span><h3><a class="toc-backref" href="#id9">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="#id10">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="#id11">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"><em class="xref std std-option">-c</em></a>, <a class="reference internal" href="#cmdoption-g"><em class="xref std std-option">-g</em></a>, etc.</p>
+<div class="section" id="options-to-control-error-and-warning-messages">
+<h3><a class="toc-backref" href="#id12">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">
+<tt class="descname">-Werror</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Werror" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turn warnings into errors.</p>
+</dd></dl>
+
+<p><tt class="docutils literal"><span class="pre">-Werror=foo</span></tt></p>
+<blockquote>
+<div>Turn warning “foo” into an error.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-Wno-error">
+<tt class="descname">-Wno-error</tt><tt class="descclassname">=foo</tt><a class="headerlink" href="#cmdoption-Wno-error" title="Permalink to this definition">¶</a></dt>
+<dd><p>Turn warning “foo” into an warning even if <a class="reference internal" href="#cmdoption-Werror"><em class="xref std std-option">-Werror</em></a> is specified.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wfoo">
+<tt class="descname">-Wfoo</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Wfoo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable warning “foo”.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wno-foo">
+<tt class="descname">-Wno-foo</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-w</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-Weverything</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-Weverything" title="Permalink to this definition">¶</a></dt>
+<dd><p><a class="reference internal" href="#diagnostics-enable-everything"><em>Enable all diagnostics.</em></a></p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pedantic">
+<tt class="descname">-pedantic</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-pedantic-errors</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-Wsystem-headers</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-ferror-limit</tt><tt class="descclassname">=123</tt><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">
+<tt class="descname">-ftemplate-backtrace-limit</tt><tt class="descclassname">=123</tt><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="#id13">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-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</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-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</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-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</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-python"><div class="highlight"><pre>test.c:2:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</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">
+<tt class="descname">-fdiagnostics-format</tt><tt class="descclassname">=clang/msvc/vi</tt><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-python"><div class="highlight"><pre>t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+</pre></div>
+</div>
+</dd>
+<dt><strong>msvc</strong></dt>
+<dd><div class="first last highlight-python"><div class="highlight"><pre>t.c(3,11) : warning: conversion specifies type 'char *' but the argument has type 'int'
+</pre></div>
+</div>
+</dd>
+<dt><strong>vi</strong></dt>
+<dd><div class="first last highlight-python"><div class="highlight"><pre>t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+</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 <tt class="docutils literal"><span class="pre">[-Woption]</span></tt> 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"><em>warning group</em></a>
+option name when outputting a warning diagnostic. For example, in
+this output:</p>
+<div class="highlight-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</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"><em>-Wextra-tokens</em></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"><em>#pragma GCC diagnostic</em></a>.</p>
+</dd>
+</dl>
+<span class="target" id="opt-fdiagnostics-show-category"></span><dl class="option">
+<dt id="cmdoption-fdiagnostics-show-category">
+<tt class="descname">-fdiagnostics-show-category</tt><tt class="descclassname">=none/id/name</tt><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-python"><div class="highlight"><pre>t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat]
+t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,1]
+t.c:3:11: warning: conversion specifies type 'char *' but the argument has type 'int' [-Wformat,Format String]
+</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>
+
+<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-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+       //
+</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-python"><div class="highlight"><pre>exprs.c:47:15:{47:8-47:14}{47:17-47:24}: error: invalid operands to binary expression ('int *' and '_Complex float')
+   P = (P-42) + Gamma*4;
+       ~~~~~~ ^ ~~~~~~~
+</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">
+<tt class="descname">-fdiagnostics-parseable-fixits</tt><tt class="descclassname"></tt><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-python"><div class="highlight"><pre>fix-it:"t.cpp":{7:25-7:29}:"Gamma"
+</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">
+<tt class="descname">-fno-elide-type</tt><tt class="descclassname"></tt><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-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
+</pre></div>
+</div>
+<p>-fno-elide-type:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument;
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fdiagnostics-show-template-tree">
+<tt class="descname">-fdiagnostics-show-template-tree</tt><tt class="descclassname"></tt><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-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<[...], map<float, [...]>>>' to 'vector<map<[...], map<double, [...]>>>' for 1st argument;
+</pre></div>
+</div>
+<p>With <a class="reference internal" href="#cmdoption-fdiagnostics-show-template-tree"><em class="xref std std-option">-fdiagnostics-show-template-tree</em></a>:</p>
+<div class="highlight-python"><div class="highlight"><pre>t.cc:4:5: note: candidate function not viable: no known conversion for 1st argument;
+  vector<
+    map<
+      [...],
+      map<
+        [float != double],
+        [...]>>>
+</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="#id14">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">
+<tt class="descname">-Wextra-tokens</tt><tt class="descclassname"></tt><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-python"><div class="highlight"><pre>test.c:28:8: warning: extra tokens at end of #endif directive [-Wextra-tokens]
+#endif bad
+       ^
+</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">
+<tt class="descname">-Wambiguous-member-template</tt><tt class="descclassname"></tt><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-python"><div class="highlight"><pre>template<typename T> struct set{};
+template<typename T> struct trait { typedef const T& type; };
+struct Value {
+  template<typename T> void set(typename trait<T>::type value) {}
+};
+void foo() {
+  Value v;
+  v.set<double>(3.2);
+}
+</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">
+<tt class="descname">-Wbind-to-temporary-copy</tt><tt class="descclassname"></tt><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-python"><div class="highlight"><pre>struct NonCopyable {
+  NonCopyable();
+private:
+  NonCopyable(const NonCopyable&);
+};
+void foo(const NonCopyable&);
+void bar() {
+  foo(NonCopyable());  // Disallowed in C++98; allowed in C++11.
+}
+</pre></div>
+</div>
+<div class="highlight-python"><div class="highlight"><pre>struct NonCopyable2 {
+  NonCopyable2();
+  NonCopyable2(NonCopyable2&);
+};
+void foo(const NonCopyable2&);
+void bar() {
+  foo(NonCopyable2());  // Disallowed in C++98; allowed in C++11.
+}
+</pre></div>
+</div>
+<p>Note that if <tt class="docutils literal"><span class="pre">NonCopyable2::NonCopyable2()</span></tt> 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="#id15">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="http://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">
+<tt class="descname">-fno-crash-diagnostics</tt><tt class="descclassname"></tt><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>
+</div>
+<div class="section" id="options-to-emit-optimization-reports">
+<h3><a class="toc-backref" href="#id16">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 <tt class="docutils literal"><span class="pre">foo()</span></tt> into <tt class="docutils literal"><span class="pre">bar()</span></tt>, 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"><div class="highlight"><pre><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>
+<div class="section" id="current-limitations">
+<h4><a class="toc-backref" href="#id17">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="#id18">Other Options</a><a class="headerlink" href="#other-options" title="Permalink to this headline">¶</a></h3>
+<p>Clang options that that don’t fit neatly into other categories.</p>
+<dl class="option">
+<dt id="cmdoption-MV">
+<tt class="descname">-MV</tt><tt class="descclassname"></tt><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>
+<div class="section" id="language-and-target-independent-features">
+<h2><a class="toc-backref" href="#id19">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="#id20">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="#id21">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"><em>-fshow-column</em></a>,
+<a class="reference internal" href="#opt-fshow-source-location"><em>-fshow-source-location</em></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"><em>-fdiagnostics-show-option</em></a>].</li>
+<li>A <a class="reference internal" href="#diagnostics-categories"><em>high-level category</em></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"><em>-fdiagnostics-show-category</em></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"><em>-fcaret-diagnostics</em></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"><em>-fdiagnostics-fixit-info</em></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"><em>-fdiagnostics-print-source-range-info</em></a>].</li>
+</ol>
+<p>For more information please see <a class="reference internal" href="#cl-diag-formatting"><em>Formatting of
+Diagnostics</em></a>.</p>
+</div>
+<div class="section" id="diagnostic-mappings">
+<h4><a class="toc-backref" href="#id22">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="#id23">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"><em>-fdiagnostics-show-category</em></a> option.
+When set to “<tt class="docutils literal"><span class="pre">name</span></tt>”, the category is printed textually in the
+diagnostic output. When it is set to “<tt class="docutils literal"><span class="pre">id</span></tt>”, a category number is
+printed. The mapping of category names to category id’s can be obtained
+by running ‘<tt class="docutils literal"><span class="pre">clang</span>   <span class="pre">--print-diagnostic-categories</span></tt>‘.</p>
+</div>
+<div class="section" id="controlling-diagnostics-via-command-line-flags">
+<h4><a class="toc-backref" href="#id24">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="#id25">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"><div class="highlight"><pre><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"><em class="xref std std-option">-Wextra-tokens</em></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"><div class="highlight"><pre><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 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"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">#warning</span></tt> and <tt class="docutils literal"><span class="pre">#error</span></tt> preprocessor
+directives, except that they may also be embedded into preprocessor macros via
+the C99 <tt class="docutils literal"><span class="pre">_Pragma</span></tt> operator, for example:</p>
+<div class="highlight-c"><div class="highlight"><pre><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="#id26">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 <tt class="docutils literal"><span class="pre">-isystem</span></tt>, but this can be overridden in
+several ways.</p>
+<p>The <tt class="docutils literal"><span class="pre">system_header</span></tt> 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"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">#include</span></tt> 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"><div class="highlight"><pre><span class="gp">$</span> clang -Ifoo -isystem bar --system-header-prefix<span class="o">=</span>x/ <span class="se">\</span>
+<span class="go">    --no-system-header-prefix=x/y/</span>
+</pre></div>
+</div>
+<p>Here, <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"x/a.h"</span></tt> is treated as including a system header, even
+if the header is found in <tt class="docutils literal"><span class="pre">foo</span></tt>, and <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"x/y/b.h"</span></tt> is treated
+as not including a system header, even if the header is found in
+<tt class="docutils literal"><span class="pre">bar</span></tt>.</p>
+<p>A <tt class="docutils literal"><span class="pre">#include</span></tt> 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="#id27">Enabling All Diagnostics</a><a class="headerlink" href="#enabling-all-diagnostics" title="Permalink to this headline">¶</a></h4>
+<p>In addition to the traditional <tt class="docutils literal"><span class="pre">-W</span></tt> flags, one can enable <strong>all</strong>
+diagnostics by passing <a class="reference internal" href="#cmdoption-Weverything"><em class="xref std std-option">-Weverything</em></a>. This works as expected
+with
+<a class="reference internal" href="#cmdoption-Werror"><em class="xref std std-option">-Werror</em></a>, and also includes the warnings from <a class="reference internal" href="#cmdoption-pedantic"><em class="xref std std-option">-pedantic</em></a>.</p>
+<p>Note that when combined with <a class="reference internal" href="#cmdoption-w"><em class="xref std std-option">-w</em></a> (which disables all warnings), that
+flag wins.</p>
+</div>
+<div class="section" id="controlling-static-analyzer-diagnostics">
+<h4><a class="toc-backref" href="#id28">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="http://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="http://clang-analyzer.llvm.org/annotations.html">annotations</a> and the
+analyzer’s <a class="reference external" href="http://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="#id29">Precompiled Headers</a><a class="headerlink" href="#precompiled-headers" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://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., Mac OS X).</p>
+<div class="section" id="generating-a-pch-file">
+<h4><a class="toc-backref" href="#id30">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"><div class="highlight"><pre><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="#id31">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"><em class="xref std std-option">-include</em></a>
+option is passed to <tt class="docutils literal"><span class="pre">clang</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -include test.h test.c -o <span class="nb">test</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">clang</span></tt> driver will first check if a PCH file for <tt class="docutils literal"><span class="pre">test.h</span></tt> is
+available; if so, the contents of <tt class="docutils literal"><span class="pre">test.h</span></tt> (and the files it includes)
+will be processed from the PCH file. Otherwise, Clang falls back to
+directly processing the content of <tt class="docutils literal"><span class="pre">test.h</span></tt>. 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"><div class="highlight"><pre><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, <tt class="docutils literal"><span class="pre">clang</span></tt> will not automatically use the PCH file for
+<tt class="docutils literal"><span class="pre">test.h</span></tt> since <tt class="docutils literal"><span class="pre">test.h</span></tt> 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"><em class="xref std std-option">-include</em></a>.</p>
+</div>
+</div>
+<div class="section" id="relocatable-pch-files">
+<h4><a class="toc-backref" href="#id32">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 <tt class="docutils literal"><span class="pre">mylib.h</span></tt>
+that will be installed into <tt class="docutils literal"><span class="pre">/usr/include</span></tt>, create a subdirectory
+<tt class="docutils literal"><span class="pre">build/usr/include</span></tt> and place the header <tt class="docutils literal"><span class="pre">mylib.h</span></tt> into that
+subdirectory. If <tt class="docutils literal"><span class="pre">mylib.h</span></tt> depends on other headers, then they can be
+stored within <tt class="docutils literal"><span class="pre">build/usr/include</span></tt> in a way that mimics the installed
+location.</p>
+<p>Building a relocatable precompiled header requires two additional
+arguments. First, pass the <tt class="docutils literal"><span class="pre">--relocatable-pch</span></tt> flag to indicate that
+the resulting PCH file should be relocatable. Second, pass
+<cite>-isysroot /path/to/build</cite>, which makes all includes for your library
+relative to the build directory. For example:</p>
+<div class="highlight-console"><div class="highlight"><pre><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, <tt class="docutils literal"><span class="pre">mylib.h</span></tt>
+can be found in <tt class="docutils literal"><span class="pre">/usr/include/mylib.h</span></tt>. If the headers are installed
+in some other system root, the <cite>-isysroot</cite> option can be used provide
+a different system root from which the headers will be based. For
+example, <cite>-isysroot /Developer/SDKs/MacOSX10.4u.sdk</cite> will look for
+<tt class="docutils literal"><span class="pre">mylib.h</span></tt> in <tt class="docutils literal"><span class="pre">/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h</span></tt>.</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="id2"></span><h3><a class="toc-backref" href="#id33">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"><tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt>:
+<a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>, a memory error
+detector.</p>
+</li>
+<li><p id="opt-fsanitize-thread"><tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>: <a class="reference internal" href="ThreadSanitizer.html"><em>ThreadSanitizer</em></a>, a data race detector.</p>
+</li>
+<li><p id="opt-fsanitize-memory"><tt class="docutils literal"><span class="pre">-fsanitize=memory</span></tt>: <a class="reference internal" href="MemorySanitizer.html"><em>MemorySanitizer</em></a>,
+a detector of uninitialized reads. Requires instrumentation of all
+program code.</p>
+</li>
+<li><p id="opt-fsanitize-undefined"><tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>: <a class="reference internal" href="UndefinedBehaviorSanitizer.html"><em>UndefinedBehaviorSanitizer</em></a>,
+a fast and compatible undefined behavior checker.</p>
+</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=dataflow</span></tt>: <a class="reference internal" href="DataFlowSanitizer.html"><em>DataFlowSanitizer</em></a>, a general data
+flow analysis.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=cfi</span></tt>: <a class="reference internal" href="ControlFlowIntegrity.html"><em>control flow integrity</em></a>
+checks. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">-fsanitize=safe-stack</span></tt>: <a class="reference internal" href="SafeStack.html"><em>safe stack</em></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"><em>list</em></a> of specific kinds of
+undefined behavior that can be detected and the <a class="reference internal" href="ControlFlowIntegrity.html#cfi-schemes"><em>list</em></a>
+of control flow integrity schemes.</p>
+<p>The <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> 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 <tt class="docutils literal"><span class="pre">-fsanitize=address</span></tt>,
+<tt class="docutils literal"><span class="pre">-fsanitize=thread</span></tt>, and <tt class="docutils literal"><span class="pre">-fsanitize=memory</span></tt> 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 <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> 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"><em>UndefinedBehaviorSanitizer</em></a>,
+except for <tt class="docutils literal"><span class="pre">-fsanitize=return</span></tt> and <tt class="docutils literal"><span class="pre">-fsanitize=unreachable</span></tt>. Some
+sanitizers may not support recovery (or not support it by default
+e.g. <a class="reference internal" href="AddressSanitizer.html"><em>AddressSanitizer</em></a>), and always crash the program after the issue
+is detected.</p>
+<p>Note that the <tt class="docutils literal"><span class="pre">-fsanitize-trap</span></tt> 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
+<tt class="docutils literal"><span class="pre">-fno-sanitize-trap</span></tt>.</p>
+<p>For example, if a command line contains the flags <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span>
+<span class="pre">-fsanitize-trap=undefined</span></tt>, the flag <tt class="docutils literal"><span class="pre">-fsanitize-recover=alignment</span></tt>
+will have no effect on its own; it will need to be accompanied by
+<tt class="docutils literal"><span class="pre">-fno-sanitize-trap=alignment</span></tt>.</p>
+</div></blockquote>
+<p><strong>-f[no-]sanitize-trap=check1,check2,...</strong></p>
+<blockquote>
+<div><p>Controls which checks enabled by the <tt class="docutils literal"><span class="pre">-fsanitize=</span></tt> 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"><em>control flow integrity</em></a> schemes and <a class="reference internal" href="UndefinedBehaviorSanitizer.html"><em>UndefinedBehaviorSanitizer</em></a>
+checks other than <tt class="docutils literal"><span class="pre">vptr</span></tt>. If this flag
+is supplied together with <tt class="docutils literal"><span class="pre">-fsanitize=undefined</span></tt>, the <tt class="docutils literal"><span class="pre">vptr</span></tt> sanitizer
+will be implicitly disabled.</p>
+<p>This flag is enabled by default for sanitizers in the <tt class="docutils literal"><span class="pre">cfi</span></tt> group.</p>
+</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-blacklist">
+<tt class="descname">-fsanitize-blacklist</tt><tt class="descclassname">=/path/to/blacklist/file</tt><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"><em>Sanitizer special case list</em></a> for file format description.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-sanitize-blacklist">
+<tt class="descname">-fno-sanitize-blacklist</tt><tt class="descclassname"></tt><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"><em>SanitizerCoverage</em></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"><em>SanitizerStats</em></a> for more details.</div></blockquote>
+<dl class="option">
+<dt id="cmdoption-fsanitize-undefined-trap-on-error">
+<tt class="descname">-fsanitize-undefined-trap-on-error</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fsanitize-undefined-trap-on-error" title="Permalink to this definition">¶</a></dt>
+<dd><p>Deprecated alias for <tt class="docutils literal"><span class="pre">-fsanitize-trap=undefined</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fsanitize-cfi-cross-dso">
+<tt class="descname">-fsanitize-cfi-cross-dso</tt><tt class="descclassname"></tt><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 <tt class="docutils literal"><span class="pre">cfi</span></tt> group to allow checking
+of cross-DSO virtual and indirect calls.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ffast-math">
+<tt class="descname">-ffast-math</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ffast-math" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable fast-math mode. This defines the <tt class="docutils literal"><span class="pre">__FAST_MATH__</span></tt> 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.
+<tt class="docutils literal"><span class="pre">+</span></tt> and <tt class="docutils literal"><span class="pre">*</span></tt> are associative, <tt class="docutils literal"><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></tt>, and
+<tt class="docutils literal"><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></tt>),</li>
+<li>operands to floating-point operations are not equal to <tt class="docutils literal"><span class="pre">NaN</span></tt> and
+<tt class="docutils literal"><span class="pre">Inf</span></tt>, and</li>
+<li><tt class="docutils literal"><span class="pre">+0</span></tt> and <tt class="docutils literal"><span class="pre">-0</span></tt> are interchangeable.</li>
+</ul>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fwhole-program-vtables">
+<tt class="descname">-fwhole-program-vtables</tt><tt class="descclassname"></tt><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"><em>hidden LTO visibility</em></a>. Requires <tt class="docutils literal"><span class="pre">-flto</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fno-assume-sane-operator-new">
+<tt class="descname">-fno-assume-sane-operator-new</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-ftrap-function</tt><tt class="descclassname">=[name]</tt><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 <tt class="docutils literal"><span class="pre">__builtin_trap()</span></tt>.</p>
+<p>LLVM code generator translates <tt class="docutils literal"><span class="pre">__builtin_trap()</span></tt> to a trap
+instruction if it is supported by the target ISA. Otherwise, the
+builtin is translated into a call to <tt class="docutils literal"><span class="pre">abort</span></tt>. 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">
+<tt class="descname">-ftls-model</tt><tt class="descclassname">=[model]</tt><a class="headerlink" href="#cmdoption-ftls-model" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select which TLS model to use.</p>
+<p>Valid values are: <tt class="docutils literal"><span class="pre">global-dynamic</span></tt>, <tt class="docutils literal"><span class="pre">local-dynamic</span></tt>,
+<tt class="docutils literal"><span class="pre">initial-exec</span></tt> and <tt class="docutils literal"><span class="pre">local-exec</span></tt>. The default value is
+<tt class="docutils literal"><span class="pre">global-dynamic</span></tt>. 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 <tt class="docutils literal"><span class="pre">tls_model</span></tt> attribute.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-femulated-tls">
+<tt class="descname">-femulated-tls</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-mhwdiv</tt><tt class="descclassname">=[values]</tt><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: <tt class="docutils literal"><span class="pre">arm</span></tt>, <tt class="docutils literal"><span class="pre">thumb</span></tt> and <tt class="docutils literal"><span class="pre">arm,thumb</span></tt>.
+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">
+<tt class="descname">-m</tt><tt class="descclassname">[no-]crc</tt><a class="headerlink" href="#cmdoption-m" 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">
+<tt class="descname">-mgeneral-regs-only</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-mcompact-branches</tt><tt class="descclassname">=[values]</tt><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: <tt class="docutils literal"><span class="pre">never</span></tt>, <tt class="docutils literal"><span class="pre">optimal</span></tt> and <tt class="docutils literal"><span class="pre">always</span></tt>.
+The default value is <tt class="docutils literal"><span class="pre">optimal</span></tt> which generates compact branches
+when a delay slot cannot be filled. <tt class="docutils literal"><span class="pre">never</span></tt> disables the usage of
+compact branches and <tt class="docutils literal"><span class="pre">always</span></tt> 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"><div class="highlight"><pre><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>
+</div>
+<div class="section" id="profile-guided-optimization">
+<h3><a class="toc-backref" href="#id34">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 <tt class="docutils literal"><span class="pre">foo</span></tt> is called more
+frequently than another function <tt class="docutils literal"><span class="pre">bar</span></tt> helps the inliner.</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="#id35">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 <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> must be used with <tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt>.
+Similarly, sampling profiles generated by external profilers must be
+converted and used with <tt class="docutils literal"><span class="pre">-fprofile-sample-use</span></tt>.</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="#id36">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 <tt class="docutils literal"><span class="pre">-gline-tables-only</span></tt> or <tt class="docutils literal"><span class="pre">-g</span></tt> 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"><div class="highlight"><pre><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"><div class="highlight"><pre><span class="gp">$</span> perf record -b ./code
+</pre></div>
+</div>
+<p>Note the use of the <tt class="docutils literal"><span class="pre">-b</span></tt> 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 <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt>.
+It is available at <a class="reference external" href="http://github.com/google/autofdo">http://github.com/google/autofdo</a>. Once built and
+installed, you can convert the <tt class="docutils literal"><span class="pre">perf.data</span></tt> file to LLVM using
+the command:</p>
+<div class="highlight-console"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">perf.data</span></tt> and the binary file <tt class="docutils literal"><span class="pre">./code</span></tt> and emit
+the profile data in <tt class="docutils literal"><span class="pre">code.prof</span></tt>. Note that if you ran <tt class="docutils literal"><span class="pre">perf</span></tt>
+without the <tt class="docutils literal"><span class="pre">-b</span></tt> flag, you need to use <tt class="docutils literal"><span class="pre">--use_lbr=false</span></tt> when
+calling <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt>.</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 <tt class="docutils literal"><span class="pre">-gline-tables-only</span></tt> and <tt class="docutils literal"><span class="pre">-fprofile-sample-use</span></tt>.</p>
+<div class="highlight-console"><div class="highlight"><pre><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="#id37">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 <tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool.</li>
+<li>Binary encoding. This uses a more efficient encoding that yields smaller
+profile files. This is the format generated by the <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt> tool
+in <a class="reference external" href="http://github.com/google/autofdo">http://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 <tt class="docutils literal"><span class="pre">create_gcov</span></tt> tool in
+<a class="reference external" href="http://github.com/google/autofdo">http://github.com/google/autofdo</a>. It can be read by LLVM and
+<tt class="docutils literal"><span class="pre">llvm-profdata</span></tt>, 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 <tt class="docutils literal"><span class="pre">create_llvm_prof</span></tt> 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="#id38">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 <tt class="docutils literal"><span class="pre">ProfileData</span></tt> library in in LLVM’s source tree
+(specifically, <tt class="docutils literal"><span class="pre">include/llvm/ProfileData/SampleProfReader.h</span></tt>).</p>
+<div class="highlight-console"><div class="highlight"><pre><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 identation 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.
+<tt class="docutils literal"><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></tt></li>
+<li>Callsite line represents the profile information of an inlined callsite.
+<tt class="docutils literal"><span class="pre">offsetA[.discriminator]:</span> <span class="pre">fnA:num_of_total_samples</span></tt></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 <tt class="docutils literal"><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></tt>.
+If the predicate <tt class="docutils literal"><span class="pre">cond</span></tt> is true 80% of the time, then the edge
+into function <tt class="docutils literal"><span class="pre">foo</span></tt> should be considered to be taken most of the
+time. But both calls to <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt> 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
+<tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt> will be at the same line, but will have
+different discriminator values. This allows the compiler to correctly
+set edge weights into <tt class="docutils literal"><span class="pre">foo</span></tt> and <tt class="docutils literal"><span class="pre">bar</span></tt>.</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"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">foo()</span></tt>, <tt class="docutils literal"><span class="pre">bar()</span></tt> and <tt class="docutils literal"><span class="pre">baz()</span></tt>,
+with <tt class="docutils literal"><span class="pre">baz()</span></tt> being the relatively more frequently called target.</p>
+</li>
+</ol>
+<p>As an example, consider a program with the call chain <tt class="docutils literal"><span class="pre">main</span> <span class="pre">-></span> <span class="pre">foo</span> <span class="pre">-></span> <span class="pre">bar</span></tt>.
+When built with optimizations enabled, the compiler may inline the
+calls to <tt class="docutils literal"><span class="pre">bar</span></tt> and <tt class="docutils literal"><span class="pre">foo</span></tt> inside <tt class="docutils literal"><span class="pre">main</span></tt>. The generated profile
+could then be something like this:</p>
+<div class="highlight-console"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">foo</span></tt>).
+Of those, 31,977 were spent inside the body of <tt class="docutils literal"><span class="pre">bar</span></tt>. The last line
+of the profile (<tt class="docutils literal"><span class="pre">2:</span> <span class="pre">0</span></tt>) corresponds to line 2 inside <tt class="docutils literal"><span class="pre">main</span></tt>. No
+samples were collected there.</p>
+</div>
+</div>
+<div class="section" id="profiling-with-instrumentation">
+<h4><a class="toc-backref" href="#id39">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
+<tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> option.</p>
+<div class="highlight-console"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">default.profraw</span></tt> file
+in the current directory. You can override that default by setting the
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> environment variable to specify an alternate file.
+Any instance of <tt class="docutils literal"><span class="pre">%p</span></tt> 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"><div class="highlight"><pre><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>
+</li>
+<li><p class="first">Combine profiles from multiple runs and convert the “raw” profile format to
+the input expected by clang. Use the <tt class="docutils literal"><span class="pre">merge</span></tt> command of the
+<tt class="docutils literal"><span class="pre">llvm-profdata</span></tt> tool to do this.</p>
+<div class="highlight-console"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt> option to specify the
+collected profile data.</p>
+<div class="highlight-console"><div class="highlight"><pre><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 <tt class="docutils literal"><span class="pre">-fprofile-generate</span></tt> and
+<tt class="docutils literal"><span class="pre">-fprofile-use</span></tt>. 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.</p>
+<dl class="option">
+<dt id="cmdoption-fprofile-generate">
+<tt class="descname">-fprofile-generate</tt><tt class="descclassname">[=<dirname>]</tt><a class="headerlink" href="#cmdoption-fprofile-generate" title="Permalink to this definition">¶</a></dt>
+<dd><p>The <tt class="docutils literal"><span class="pre">-fprofile-generate</span></tt> and <tt class="docutils literal"><span class="pre">-fprofile-generate=</span></tt> flags will use
+an alterantive instrumentation method for profile generation. When
+given a directory name, it generates the profile file
+<tt class="docutils literal"><span class="pre">default.profraw</span></tt> in the directory named <tt class="docutils literal"><span class="pre">dirname</span></tt>. If <tt class="docutils literal"><span class="pre">dirname</span></tt>
+does not exist, it will be created at runtime. The environment variable
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> can be used to override the directory and
+filename for the profile file at runtime. For example,</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ -O2 -fprofile-generate<span class="o">=</span>yyy/zzz code.cc -o code
+</pre></div>
+</div>
+<p>When <tt class="docutils literal"><span class="pre">code</span></tt> is executed, the profile will be written to the file
+<tt class="docutils literal"><span class="pre">yyy/zzz/default.profraw</span></tt>. This can be altered at runtime via the
+<tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> environment variable:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nv">LLVM_PROFILE_FILE</span><span class="o">=</span>/tmp/myprofile/code.profraw ./code
+</pre></div>
+</div>
+<p>The above invocation will produce the profile file
+<tt class="docutils literal"><span class="pre">/tmp/myprofile/code.profraw</span></tt> instead of <tt class="docutils literal"><span class="pre">yyy/zzz/default.profraw</span></tt>.
+Notice that <tt class="docutils literal"><span class="pre">LLVM_PROFILE_FILE</span></tt> overrides the directory <em>and</em> the file
+name for the profile file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fprofile-use">
+<tt class="descname">-fprofile-use</tt><tt class="descclassname">[=<pathname>]</tt><a class="headerlink" href="#cmdoption-fprofile-use" title="Permalink to this definition">¶</a></dt>
+<dd><p>Without any other arguments, <tt class="docutils literal"><span class="pre">-fprofile-use</span></tt> behaves identically to
+<tt class="docutils literal"><span class="pre">-fprofile-instr-use</span></tt>. Otherwise, if <tt class="docutils literal"><span class="pre">pathname</span></tt> is the full path to a
+profile file, it reads from that file. If <tt class="docutils literal"><span class="pre">pathname</span></tt> is a directory name,
+it reads from <tt class="docutils literal"><span class="pre">pathname/default.profdata</span></tt>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="disabling-instrumentation">
+<h4><a class="toc-backref" href="#id40">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 <tt class="docutils literal"><span class="pre">-fno-profile-instr-generate</span></tt> (or
+<tt class="docutils literal"><span class="pre">-fno-profile-generate</span></tt>) to disable profile generation, and
+<tt class="docutils literal"><span class="pre">-fno-profile-instr-use</span></tt> (or <tt class="docutils literal"><span class="pre">-fno-profile-use</span></tt>) to disable profile use.</p>
+<p>Note that these flags should appear after the corresponding profile
+flags to have an effect.</p>
+</div>
+</div>
+<div class="section" id="controlling-debug-information">
+<h3><a class="toc-backref" href="#id41">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="#id42">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">
+<tt class="descname">-g0</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-gline-tables-only</tt><tt class="descclassname"></tt><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 <tt class="docutils literal"><span class="pre">gdb</span></tt> or <tt class="docutils literal"><span class="pre">addr2line</span></tt>).  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">
+<tt class="descname">-fstandalone-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-fstandalone-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>Clang supports a number of optimizations to reduce the size of debug
+information in the binary. They work based on the assumption that
+the debug type information can be spread out over multiple
+compilation units.  For instance, Clang will not emit type
+definitions for types that are not needed by a module and could be
+replaced with a forward declaration.  Further, Clang will only emit
+type info for a dynamic C++ class in the module that contains the
+vtable for the class.</p>
+<p>The <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">
+<tt class="descname">-fno-standalone-debug</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-g</tt><tt class="descclassname"></tt><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-debugger-tuning">
+<h4><a class="toc-backref" href="#id43">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">
+<span id="cmdoption-glldb"></span><span id="cmdoption-gsce"></span><tt class="descname">-ggdb</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-glldb</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-gsce</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-ggdb" title="Permalink to this definition">¶</a></dt>
+<dd><p>Tune the debug info for the <tt class="docutils literal"><span class="pre">gdb</span></tt>, <tt class="docutils literal"><span class="pre">lldb</span></tt>, or Sony Computer Entertainment
+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="comment-parsing-options">
+<h3><a class="toc-backref" href="#id44">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 <tt class="docutils literal"><span class="pre">//</span></tt> and
+<tt class="docutils literal"><span class="pre">/*</span></tt>.</p>
+<dl class="option">
+<dt id="cmdoption-Wdocumentation">
+<tt class="descname">-Wdocumentation</tt><tt class="descclassname"></tt><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 <tt class="docutils literal"><span class="pre">\param</span></tt> commands name parameters that actually
+present in the function signature, checking that <tt class="docutils literal"><span class="pre">\returns</span></tt> is used only on
+functions that actually return a value etc.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-Wno-documentation-unknown-command">
+<tt class="descname">-Wno-documentation-unknown-command</tt><tt class="descclassname"></tt><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">
+<tt class="descname">-fparse-all-comments</tt><tt class="descclassname"></tt><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 <tt class="docutils literal"><span class="pre">//</span></tt> and <tt class="docutils literal"><span class="pre">/*</span></tt>).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-fcomment-block-commands">
+<tt class="descname">-fcomment-block-commands</tt><tt class="descclassname">=[commands]</tt><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. <tt class="docutils literal"><span class="pre">-fcomment-block-commands=foo,bar</span></tt> defines
+custom commands <tt class="docutils literal"><span class="pre">\foo</span></tt> and <tt class="docutils literal"><span class="pre">\bar</span></tt>.</p>
+<p>It is also possible to use <tt class="docutils literal"><span class="pre">-fcomment-block-commands</span></tt> several times; e.g.
+<tt class="docutils literal"><span class="pre">-fcomment-block-commands=foo</span> <span class="pre">-fcomment-block-commands=bar</span></tt> 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="#id45">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="#id46">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"><em>Clang Language Extensions</em></a>.</p>
+</div>
+<div class="section" id="differences-between-various-standard-modes">
+<h3><a class="toc-backref" href="#id47">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, c94, c99, gnu99, c11,
+gnu11, 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
+<tt class="docutils literal"><span class="pre">-pedantic-errors</span></tt> to request an error if a feature from a later standard
+revision is used in an earlier mode.</p>
+<p>Differences between all <tt class="docutils literal"><span class="pre">c*</span></tt> and <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">c*</span></tt> modes define “<tt class="docutils literal"><span class="pre">__STRICT_ANSI__</span></tt>”.</li>
+<li>Target-specific defines not prefixed by underscores, like “linux”,
+are defined in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes.</li>
+<li>Trigraphs default to being off in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes; they can be enabled by
+the -trigraphs option.</li>
+<li>The parser recognizes “asm” and “typeof” as keywords in <tt class="docutils literal"><span class="pre">gnu*</span></tt> modes;
+the variants “<tt class="docutils literal"><span class="pre">__asm__</span></tt>” and “<tt class="docutils literal"><span class="pre">__typeof__</span></tt>” are recognized in all
+modes.</li>
+<li>The Apple “blocks” extension is recognized by default in <tt class="docutils literal"><span class="pre">gnu*</span></tt> 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. <tt class="docutils literal"><span class="pre">c*</span></tt> modes are strictly compliant and treat these as VLAs.</li>
+</ul>
+<p>Differences between <tt class="docutils literal"><span class="pre">*89</span></tt> and <tt class="docutils literal"><span class="pre">*99</span></tt> modes:</p>
+<ul class="simple">
+<li>The <tt class="docutils literal"><span class="pre">*99</span></tt> modes default to implementing “inline” as specified in C99,
+while the <tt class="docutils literal"><span class="pre">*89</span></tt> modes implement the GNU version. This can be
+overridden for individual functions with the <tt class="docutils literal"><span class="pre">__gnu_inline__</span></tt>
+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: “<tt class="docutils literal"><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></tt>”.)</li>
+<li><tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> is not defined in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>“inline” is not recognized as a keyword in c89 mode.</li>
+<li>“restrict” is not recognized as a keyword in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>Commas are allowed in integer constant expressions in <tt class="docutils literal"><span class="pre">*99</span></tt> modes.</li>
+<li>Arrays which are not lvalues are not implicitly promoted to pointers
+in <tt class="docutils literal"><span class="pre">*89</span></tt> modes.</li>
+<li>Some warnings are different.</li>
+</ul>
+<p>Differences between <tt class="docutils literal"><span class="pre">*99</span></tt> and <tt class="docutils literal"><span class="pre">*11</span></tt> modes:</p>
+<ul class="simple">
+<li>Warnings for use of C11 features are disabled.</li>
+<li><tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> is defined to <tt class="docutils literal"><span class="pre">201112L</span></tt> rather than <tt class="docutils literal"><span class="pre">199901L</span></tt>.</li>
+</ul>
+<p>c94 mode is identical to c89 mode except that digraphs are enabled in
+c94 mode (FIXME: And <tt class="docutils literal"><span class="pre">__STDC_VERSION__</span></tt> should be defined!).</p>
+</div>
+<div class="section" id="gcc-extensions-not-implemented-yet">
+<h3><a class="toc-backref" href="#id48">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 (<tt class="docutils literal"><span class="pre">_Decimal32</span></tt> and
+friends) or fixed-point types (<tt class="docutils literal"><span class="pre">_Fract</span></tt> 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"><div class="highlight"><pre><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 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
+<tt class="docutils literal"><span class="pre">__builtin_va_arg_pack</span></tt>/<tt class="docutils literal"><span class="pre">__builtin_va_arg_pack_len</span></tt>. 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"><em>C++ Language Features</em></a>. Also, this
+list does not include bugs in mostly-implemented features; please see
+the <a class="reference external" href="http://llvm.org/bugs/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="#id49">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 <tt class="docutils literal"><span class="pre">__builtin_apply</span></tt> 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="#id50">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 <tt class="docutils literal"><span class="pre">-fms-extensions</span></tt> 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 <tt class="docutils literal"><span class="pre">__declspec(dllexport)</span></tt> and <tt class="docutils literal"><span class="pre">#pragma</span>
+<span class="pre">comment(lib)</span></tt> are well supported.</p>
+<p>clang has a <tt class="docutils literal"><span class="pre">-fms-compatibility</span></tt> 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="http://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><tt class="docutils literal"><span class="pre">-fdelayed-template-parsing</span></tt> 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
+<tt class="docutils literal"><span class="pre">_MSC_VER</span></tt> and <tt class="docutils literal"><span class="pre">_MSC_FULL_VER</span></tt> macros. These default to the values of 1800
+and 180000000 respectively, making clang look like an early release of Visual
+C++ 2013. The <tt class="docutils literal"><span class="pre">-fms-compatibility-version=</span></tt> 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, <tt class="docutils literal"><span class="pre">-fms-compatibility-version=19</span></tt> will enable C++14 features and define
+<tt class="docutils literal"><span class="pre">char16_t</span></tt> and <tt class="docutils literal"><span class="pre">char32_t</span></tt> as builtin types.</p>
+</div>
+</div>
+<div class="section" id="cxx">
+<span id="id3"></span><h2><a class="toc-backref" href="#id51">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="#id52">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">
+<tt class="descname">-fbracket-depth</tt><tt class="descclassname">=N</tt><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">
+<tt class="descname">-fconstexpr-depth</tt><tt class="descclassname">=N</tt><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-ftemplate-depth">
+<tt class="descname">-ftemplate-depth</tt><tt class="descclassname">=N</tt><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 256.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-foperator-arrow-depth">
+<tt class="descname">-foperator-arrow-depth</tt><tt class="descclassname">=N</tt><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="#id53">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="id4"></span><h2><a class="toc-backref" href="#id54">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="#id55">OpenMP Features</a><a class="headerlink" href="#openmp-features" title="Permalink to this headline">¶</a></h2>
+<p>Clang supports all OpenMP 3.1 directives and clauses.  In addition, some
+features of OpenMP 4.0 are supported.  For example, <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">simd</span></tt>,
+<tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">for</span> <span class="pre">simd</span></tt>, <tt class="docutils literal"><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></tt> directives, extended
+set of atomic constructs, <tt class="docutils literal"><span class="pre">proc_bind</span></tt> clause for all parallel-based
+directives, <tt class="docutils literal"><span class="pre">depend</span></tt> clause for <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">task</span></tt> directive (except for
+array sections), <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">cancel</span></tt> and <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">cancellation</span> <span class="pre">point</span></tt>
+directives, and <tt class="docutils literal"><span class="pre">#pragma</span> <span class="pre">omp</span> <span class="pre">taskgroup</span></tt> directive.</p>
+<p>Use <cite>-fopenmp</cite> to enable OpenMP. Support for OpenMP can be disabled with
+<cite>-fno-openmp</cite>.</p>
+<div class="section" id="id5">
+<h3><a class="toc-backref" href="#id56">Controlling implementation limits</a><a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-fopenmp-use-tls">
+<tt class="descname">-fopenmp-use-tls</tt><tt class="descclassname"></tt><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="target-specific-features-and-limitations">
+<span id="target-features"></span><h2><a class="toc-backref" href="#id57">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="#id58">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="#id59">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 (Mac OS X), 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 <tt class="docutils literal"><span class="pre">x86_64-mingw32</span></tt>, passing i128(by value) is incompatible with the
+Microsoft x64 calling convention. You might need to tweak
+<tt class="docutils literal"><span class="pre">WinX86_64ABIInfo::classify()</span></tt> 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 <tt class="docutils literal"><span class="pre">asm(".code16gcc")</span></tt> 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="#id60">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="#id61">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="#id62">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 <tt class="docutils literal"><span class="pre">lib/Basic/Targets.cpp</span></tt> 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 <tt class="docutils literal"><span class="pre">lib/CodeGen/CGCall.cpp</span></tt> 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="#id63">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-mac-os-x">
+<h4><a class="toc-backref" href="#id64">Darwin (Mac OS X)</a><a class="headerlink" href="#darwin-mac-os-x" 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="#id65">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"><em>Microsoft Extensions</em></a>.</p>
+<div class="section" id="cygwin">
+<h5><a class="toc-backref" href="#id66">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="#id67">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><tt class="docutils literal"><span class="pre">C:/mingw/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">C:/mingw/lib</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++</span></tt></li>
+</ul>
+<p>On MSYS, a few tests might fail.</p>
+</div>
+<div class="section" id="mingw-w64">
+<h5><a class="toc-backref" href="#id68">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><tt class="docutils literal"><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></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/gcc.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/clang.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/clang++.exe</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include/c++/GCC_version/backward</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../x86_64-w64-mingw32/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../i686-w64-mingw32/include</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">some_directory/bin/../include</span></tt></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
+<tt class="docutils literal"><span class="pre">i686-w64-mingw32</span></tt> (or <tt class="docutils literal"><span class="pre">x86_64-w64-mingw32</span></tt>) to be present on PATH.</p>
+<p><a class="reference external" href="http://llvm.org/bugs/show_bug.cgi?id=9072">Some tests might fail</a> on
+<tt class="docutils literal"><span class="pre">x86_64-w64-mingw32</span></tt>.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="clang-cl">
+<span id="id6"></span><h2><a class="toc-backref" href="#id69">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 driver, 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="http://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx">vcvars32.bat</a>.</p>
+<p>clang-cl can also be used from inside Visual Studio  by using an LLVM Platform
+Toolset.</p>
+<div class="section" id="id7">
+<h3><a class="toc-backref" href="#id70">Command-Line Options</a><a class="headerlink" href="#id7" 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 <tt class="docutils literal"><span class="pre">/</span></tt> or <tt class="docutils literal"><span class="pre">-</span></tt>. It also supports
+some of Clang’s core options, such as the <tt class="docutils literal"><span class="pre">-W</span></tt> 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-python"><div class="highlight"><pre>clang-cl.exe: warning: argument unused during compilation: '/AI'
+</pre></div>
+</div>
+</div></blockquote>
+<p>To suppress warnings about unused arguments, use the <tt class="docutils literal"><span class="pre">-Qunused-arguments</span></tt> option.</p>
+<p>Options that are not known to clang-cl will be ignored by default. Use the
+<tt class="docutils literal"><span class="pre">-Werror=unknown-argument</span></tt> option in order to treat them as errors. If these
+options are spelled with a leading <tt class="docutils literal"><span class="pre">/</span></tt>, they will be mistaken for a filename:</p>
+<blockquote>
+<div><div class="highlight-python"><div class="highlight"><pre>clang-cl.exe: error: no such file or directory: '/foobar'
+</pre></div>
+</div>
+</div></blockquote>
+<p>Please <a class="reference external" href="http://llvm.org/bugs/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 <tt class="docutils literal"><span class="pre">clang-cl</span> <span class="pre">/?</span></tt> to see a list of supported options:</p>
+<blockquote>
+<div><div class="highlight-python"><div class="highlight"><pre>CL.EXE COMPATIBILITY OPTIONS:
+  /?                     Display available options
+  /arch:<value>          Set architecture for code generation
+  /Brepro-               Emit an object file which cannot be reproduced over time
+  /Brepro                Emit an object file which can be reproduced over time
+  /C                     Don't discard comments when preprocessing
+  /c                     Compile only
+  /D <macro[=value]>     Define macro
+  /EH<value>             Exception handling model
+  /EP                    Disable linemarker output and preprocess to stdout
+  /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 directory> Output assembly code to this file during compilation (with /FA)
+  /Fe<file or directory> Set output executable file or directory (ends in / or \)
+  /FI <value>            Include file before parsing
+  /Fi<file>              Set preprocess output file name (with /P)
+  /Fo<file or directory> Set output object file, or directory (ends in / or \) (with /c)
+  /fp:except-
+  /fp:except
+  /fp:fast
+  /fp:precise
+  /fp:strict
+  /Fp<filename>          Set pch filename (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
+  /GR-                   Disable emission of RTTI data
+  /GR                    Enable emission of RTTI data
+  /Gr                    Set __fastcall as a default calling convention
+  /GS-                   Disable buffer security check
+  /GS                    Enable buffer security check
+  /Gs<value>             Set stack probe size
+  /Gv                    Set __vectorcall as a default calling convention
+  /Gw-                   Don't put each data item in its own section
+  /Gw                    Put each data item in its own section
+  /GX-                   Enable exception handling
+  /GX                    Enable exception handling
+  /Gy-                   Don't put each function in its own section
+  /Gy                    Put each function in its own section
+  /Gz                    Set __stdcall as a default calling convention
+  /help                  Display available options
+  /imsvc <dir>           Add directory to system include search path, as if part of %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
+  /Od                    Disable optimization
+  /Oi-                   Disable use of builtin functions
+  /Oi                    Enable use of builtin functions
+  /Os                    Optimize for size
+  /Ot                    Optimize for speed
+  /O<value>              Optimization level
+  /o <file or directory> Set output file or directory (ends in / or \)
+  /P                     Preprocess to file
+  /Qvec-                 Disable the loop vectorization passes
+  /Qvec                  Enable the loop vectorization passes
+  /showIncludes          Print info about included files to stderr
+  /std:<value>           Language standard to compile for
+  /TC                    Treat all source files as C
+  /Tc <filename>         Specify a C source file
+  /TP                    Treat all source files as C++
+  /Tp <filename>         Specify a C++ source file
+  /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 -Wall and -Wextra
+  /WX-                   Do not treat warnings as errors
+  /WX                    Treat warnings as errors
+  /w                     Disable all warnings
+  /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: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
+  /Zd                    Emit debug line number tables only
+  /Zi                    Alias for /Z7. Does not produce PDBs.
+  /Zl                    Don't mention any default libraries in the object file
+  /Zp                    Set the default maximum struct packing alignment to 1
+  /Zp<value>             Specify the 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
+  -fansi-escape-codes     Use ANSI escape codes for diagnostics
+  -fcolor-diagnostics     Use colors in diagnostics
+  -fdiagnostics-parseable-fixits
+                          Print fix-its in machine parseable form
+  -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-sanitize-coverage=<value>
+                          Disable specified features of coverage instrumentation for Sanitizers
+  -fno-sanitize-recover=<value>
+                          Disable recovery for specified sanitizers
+  -fno-sanitize-trap=<value>
+                          Disable trapping for specified sanitizers
+  -fsanitize-blacklist=<value>
+                          Path to blacklist file for sanitizers
+  -fsanitize-coverage=<value>
+                          Specify the type of coverage instrumentation for Sanitizers
+  -fsanitize-recover=<value>
+                          Enable recovery for specified sanitizers
+  -fsanitize-trap=<value> Enable trapping for specified sanitizers
+  -fsanitize=<check>      Turn on runtime checks for various forms of undefined or suspicious
+                          behavior. See user manual for available checks
+  -gcodeview              Generate CodeView debug information
+  -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
+  -Qunused-arguments      Don't emit warning for unused driver arguments
+  -R<remark>              Enable the specified remark
+  --target=<value>        Generate code for the given target
+  -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-fallback-option">
+<h4><a class="toc-backref" href="#id71">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 <tt class="docutils literal"><span class="pre">/fallback</span></tt> 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">
+      
+        <p>
+        «  <a href="ReleaseNotes.html">Clang 3.9 Release Notes</a>
+          ::  
+        <a class="uplink" href="index.html">Contents</a>
+          ::  
+        <a href="LanguageExtensions.html">Clang Language Extensions</a>  Â»
+        </p>
+
+      </div>
+
+    <div class="footer">
+        © Copyright 2007-2016, The Clang Team.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.9.0/tools/clang/docs/_images/DriverArchitecture.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_images/DriverArchitecture.png?rev=280493&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.9.0/tools/clang/docs/_images/DriverArchitecture.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.9.0/tools/clang/docs/_images/PCHLayout.png
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_images/PCHLayout.png?rev=280493&view=auto
==============================================================================
Binary file - no diff available.

Propchange: www-releases/trunk/3.9.0/tools/clang/docs/_images/PCHLayout.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/AddressSanitizer.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/AddressSanitizer.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/AddressSanitizer.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/AddressSanitizer.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,287 @@
+================
+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 (to some extent)
+* Double-free, invalid free
+* Memory leaks (experimental)
+
+Typical slowdown introduced by AddressSanitizer is **2x**.
+
+How to build
+============
+
+Build LLVM/Clang with `CMake <http://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 OS X 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 OS X.
+
+Memory leak detection
+---------------------
+
+For more information on leak detector in AddressSanitizer, see
+:doc:`LeakSanitizer`. The leak detection is turned on by default on Linux;
+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
+function 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)``.
+
+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 is not supported.
+
+Supported Platforms
+===================
+
+AddressSanitizer is supported on:
+
+* Linux i386/x86\_64 (tested on Ubuntu 12.04)
+* OS X 10.7 - 10.11 (i386/x86\_64)
+* iOS Simulator
+* Android ARM
+* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
+
+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.
+
+More Information
+================
+
+`<https://github.com/google/sanitizers/wiki/AddressSanitizer>`_

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/AttributeReference.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/AttributeReference.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/AttributeReference.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/AttributeReference.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,2736 @@
+..
+  -------------------------------------------------------------------
+  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:
+
+Introduction
+============
+
+This page lists the attributes currently supported by Clang.
+
+Function Attributes
+===================
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.
+
+
+abi_tag (gnu::abi_tag)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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. Therefor, 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, clang::acquire_capability, clang::acquire_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Marks a function as acquiring a capability.
+
+
+interrupt
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Clang supports the GNU style ``__attribute__((interrupt))`` attribute on
+x86/x86-64 targets.The compiler generates function entry and exit sequences
+suitable for use in an interrupt handler when this attribute is present.
+The 'IRET' instruction, instead of the 'RET' instruction, is used to return
+from interrupt or exception handlers.  All registers, except for the EFLAGS
+register which is restored by the 'IRET' instruction, are preserved by the
+compiler.
+
+Any interruptible-without-stack-switch code must be compiled with
+-mno-red-zone since interrupt handlers can and will, because of the
+hardware design, touch the red zone.
+
+1. interrupt handler must be declared with a mandatory pointer argument:
+
+  .. code-block:: c
+
+    struct interrupt_frame
+    {
+      uword_t ip;
+      uword_t cs;
+      uword_t flags;
+      uword_t sp;
+      uword_t ss;
+    };
+
+    __attribute__ ((interrupt))
+    void f (struct interrupt_frame *frame) {
+      ...
+    }
+
+2. exception handler:
+
+  The exception handler is very similar to the interrupt handler with
+  a different mandatory function signature:
+
+  .. code-block:: c
+
+    __attribute__ ((interrupt))
+    void f (struct interrupt_frame *frame, uword_t error_code) {
+      ...
+    }
+
+  and compiler pops 'ERROR_CODE' off stack before the 'IRET' instruction.
+
+  The exception handler should only be used for exceptions which push an
+  error code and all other exceptions must use the interrupt handler.
+  The system will crash if the wrong handler is used.
+
+
+assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)
+-------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.
+
+
+assume_aligned (gnu::assume_aligned)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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 Mac OS X 10.4,
+deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7.  This information
+is used by Clang to determine when it is safe to use ``f``: for example, if
+Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``
+succeeds.  If Clang is instructed to compile code for Mac OS X 10.6, the call
+succeeds but Clang emits a warning specifying that the function is deprecated.
+Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call
+fails because ``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.  Only the availability attribute with the
+platform corresponding to the target platform will be used; any others will be
+ignored.  If no availability attribute specifies availability for the current
+target platform, the availability attributes are ignored.  Supported platforms
+are:
+
+``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 Mac OS X 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
+
+
+_Noreturn
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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.
+
+
+noreturn
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","X","","", ""
+
+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.
+
+
+carries_dependency
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+deprecated (gnu::deprecated)
+----------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","X","", ""
+
+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.
+
+
+disable_tail_calls (clang::disable_tail_calls)
+----------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+.. 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.
+
+
+flatten (gnu::flatten)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+format (gnu::format)
+--------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+ifunc (gnu::ifunc)
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+``__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 take no arguments and 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 targets support this attribute when using binutils v2.20.1 or higher and glibc v2.11.1 or higher.  Non-ELF targets currently do not support this attribute.
+
+
+internal_linkage (clang::internal_linkage)
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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".
+
+
+noalias
+-------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","X","", ""
+
+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.
+
+
+noduplicate (clang::noduplicate)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+no_sanitize (clang::no_sanitize)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Use the ``no_sanitize`` attribute on a function declaration to specify
+that a particular instrumentation or set of instrumentations should not be
+applied to that function. The attribute takes a list of string literals,
+which have the same meaning as values accepted by the ``-fno-sanitize=``
+flag. For example, ``__attribute__((no_sanitize("address", "thread")))``
+specifies that AddressSanitizer and ThreadSanitizer should not be applied
+to the function.
+
+See :ref:`Controlling Code Generation <controlling-code-generation>` for a
+full list of supported sanitizer flags.
+
+
+no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+.. _langext-address_sanitizer:
+
+Use ``__attribute__((no_sanitize_address))`` on a function declaration to
+specify that address safety instrumentation (e.g. AddressSanitizer) should
+not be applied to that function.
+
+
+no_sanitize_thread
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+.. _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_sanitize_memory
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+.. _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_split_stack (gnu::no_split_stack)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+not_tail_called (clang::not_tail_called)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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;
+    };
+
+
+#pragma omp declare simd
+------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","", "X"
+
+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:: c
+
+  #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:: c
+
+  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", "__declspec", "Keyword", "Pragma"
+
+   "","","","", "X"
+
+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
+
+
+objc_boxable
+------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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_method_family
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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{};
+                      ^
+
+
+objc_runtime_name
+-----------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.
+
+
+optnone (clang::optnone)
+------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+overloadable
+------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.
+
+The declaration of ``overloadable`` functions is restricted to function
+declarations and definitions.  Most importantly, if any function with a given
+name is given the ``overloadable`` attribute, then all function declarations
+and definitions with that name (and in that scope) must have the
+``overloadable`` attribute.  This rule even applies to redeclarations of
+functions whose original declaration had 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 g(int) __attribute__((overloadable));
+  int g(int) { } // error: redeclaration of "g" must also 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.
+
+Query for this feature with ``__has_extension(attribute_overloadable)``.
+
+
+release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+Marks a function as releasing a capability.
+
+
+kernel
+------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+``__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
+
+
+target (gnu::target)
+--------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)
+---------------------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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).
+
+
+nodiscard, warn_unused_result, clang::warn_unused_result, gnu::warn_unused_result
+---------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument)
+------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+``__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.
+
+
+Variable Attributes
+===================
+
+
+dllexport (gnu::dllexport)
+--------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","X","", ""
+
+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 (gnu::dllimport)
+--------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","X","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "","","","", "X"
+
+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
+
+
+nodebug (gnu::nodebug)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+nosvm
+-----
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.
+
+
+pass_object_size
+----------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+.. 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.
+
+
+section (gnu::section, __declspec(allocate))
+--------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","X","", ""
+
+The ``section`` attribute allows you to specify a specific section a
+global variable or function should be in after translation.
+
+
+swiftcall (gnu::swiftcall)
+--------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+swift_context (gnu::swift_context)
+----------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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 (gnu::swift_error_result)
+--------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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 (gnu::swift_indirect_result)
+--------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall``
+function as having the special indirect-result ABI treatmenet.
+
+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).
+
+
+tls_model (gnu::tls_model)
+--------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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.
+
+
+thread
+------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","X","", ""
+
+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.
+
+
+maybe_unused, unused, gnu::unused
+---------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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);
+  }
+
+
+Type Attributes
+===============
+
+
+align_value
+-----------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.
+
+
+empty_bases
+-----------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","X","", ""
+
+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.
+
+
+flag_enum
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.
+
+
+lto_visibility_public (clang::lto_visibility_public)
+----------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","X","","", ""
+
+See :doc:`LTOVisibility`.
+
+
+layout_version
+--------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","X","", ""
+
+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.
+
+
+__single_inhertiance, __multiple_inheritance, __virtual_inheritance
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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 {};
+
+
+novtable
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","X","", ""
+
+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.
+
+
+Statement Attributes
+====================
+
+
+fallthrough, clang::fallthrough
+-------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","X","","", ""
+
+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();
+  }
+
+
+#pragma clang loop
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","", "X"
+
+The ``#pragma clang loop`` directive allows loop optimization hints to be
+specified for the subsequent loop. The directive allows vectorization,
+interleaving, and unrolling to be enabled or disabled. Vector width as well
+as interleave and unrolling count can be manually specified. See
+`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", "__declspec", "Keyword", "Pragma"
+
+   "","","","", "X"
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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.
+
+
+__attribute__((opencl_unroll_hint))
+-----------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.
+
+
+AMD GPU Register Attributes
+===========================
+Clang supports attributes for controlling register usage on AMD GPU
+targets. These attributes may be attached to a kernel function
+definition and is an optimization hint to the backend for the maximum
+number of registers to use. This is useful in cases where register
+limited occupancy is known to be an important factor for the
+performance for the kernel.
+
+The semantics are as follows:
+
+- The backend will attempt to limit the number of used registers to
+  the specified value, but the exact number used is not
+  guaranteed. The number used may be rounded up to satisfy the
+  allocation requirements or ABI constraints of the subtarget. For
+  example, on Southern Islands VGPRs may only be allocated in
+  increments of 4, so requesting a limit of 39 VGPRs will really
+  attempt to use up to 40. Requesting more registers than the
+  subtarget supports will truncate to the maximum allowed. The backend
+  may also use fewer registers than requested whenever possible.
+
+- 0 implies the default no limit on register usage.
+
+- Ignored on older VLIW subtargets which did not have separate scalar
+  and vector registers, R600 through Northern Islands.
+
+amdgpu_num_sgpr
+---------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Clang supports the
+``__attribute__((amdgpu_num_sgpr(<num_registers>)))`` attribute on AMD
+Southern Islands GPUs and later for controlling the number of scalar
+registers. A typical value would be between 8 and 104 in increments of
+8.
+
+Due to common instruction constraints, an additional 2-4 SGPRs are
+typically required for internal use depending on features used. This
+value is a hint for the total number of SGPRs to use, and not the
+number of user SGPRs, so no special consideration needs to be given
+for these.
+
+
+amdgpu_num_vgpr
+---------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Clang supports the
+``__attribute__((amdgpu_num_vgpr(<num_registers>)))`` attribute on AMD
+Southern Islands GPUs and later for controlling the number of vector
+registers. A typical value would be between 4 and 256 in increments
+of 4.
+
+
+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.
+
+fastcall (gnu::fastcall, __fastcall, _fastcall)
+-----------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","X", ""
+
+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 (gnu::ms_abi)
+--------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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 (gnu::pcs)
+--------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.
+
+
+regparm (gnu::regparm)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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 (gnu::stdcall, __stdcall, _stdcall)
+-------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","X", ""
+
+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 (gnu::thiscall, __thiscall, _thiscall)
+-----------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","X", ""
+
+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 (__vectorcall, _vectorcall)
+--------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","X", ""
+
+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. Homogenous 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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.  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", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.
+``arg_kind`` is an identifier that should be used when annotating all
+applicable type tags.
+
+This attribute is primarily useful for checking arguments of variadic functions
+(``pointer_with_type_tag`` can be used in most non-variadic cases).
+
+For example:
+
+.. code-block:: c++
+
+  int fcntl(int fd, int cmd, ...)
+      __attribute__(( argument_with_type_tag(fcntl,3,2) ));
+
+
+pointer_with_type_tag
+---------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+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.
+
+For example:
+
+.. code-block:: c++
+
+  int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+      __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+
+type_tag_for_datatype
+---------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","","","", ""
+
+Clang supports annotating type tags of two forms.
+
+* **Type tag that is an expression containing a reference to some declared
+  identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a
+  declaration with that identifier:
+
+  .. code-block:: c++
+
+    extern struct mpi_datatype mpi_datatype_int
+        __attribute__(( type_tag_for_datatype(mpi,int) ));
+    #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
+
+* **Type tag that is an integral literal.** Introduce a ``static const``
+  variable with a corresponding initializer value and attach
+  ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration,
+  for example:
+
+  .. code-block:: c++
+
+    #define MPI_INT ((MPI_Datatype) 42)
+    static const MPI_Datatype mpi_datatype_int
+        __attribute__(( type_tag_for_datatype(mpi,int) )) = 42
+
+The attribute also accepts an optional third argument that determines how the
+expression is compared to the type tag.  There are two supported flags:
+
+* ``layout_compatible`` will cause types to be compared according to
+  layout-compatibility rules (C++11 [class.mem] p 17, 18).  This is
+  implemented to support annotating types like ``MPI_DOUBLE_INT``.
+
+  For example:
+
+  .. code-block:: c++
+
+    /* In mpi.h */
+    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)
+
+    /* In user code */
+    struct my_pair { double a; int b; };
+    struct my_pair *buffer;
+    MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ...  */); // no warning
+
+    struct my_int_pair { int a; int b; }
+    struct my_int_pair *buffer2;
+    MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ...  */); // warning: actual buffer element
+                                                      // type 'struct my_int_pair'
+                                                      // doesn't match specified MPI_Datatype
+
+* ``must_be_null`` specifies that the expression should be a null pointer
+  constant, for example:
+
+  .. code-block:: c++
+
+    /* In mpi.h */
+    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)
+
+    /* In user code */
+    MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ...  */); // warning: MPI_DATATYPE_NULL
+                                                        // was specified but buffer
+                                                        // is not a null pointer
+
+
+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 (__constant)
+---------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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 (__generic)
+-------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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 (__global)
+-----------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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 (__local)
+---------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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 (__private)
+-------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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.
+
+
+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 (gnu::nonnull)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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 (gnu::returns_nonnull)
+--------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "X","X","","", ""
+
+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
+
+
+_Nonnull
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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", "__declspec", "Keyword", "Pragma"
+
+   "","","","X", ""
+
+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.
+
+

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/AutomaticReferenceCounting.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,2291 @@
+.. 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:
+     * http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/
+     */
+    /*
+     * Automatic numbering for the TOC.
+     * This is wrong from the semantics point of view, since it is an ordered
+     * list, but uses "ul" tag.
+     */
+    div#contents.contents.local ul {
+      counter-reset: toc-section;
+      list-style-type: none;
+    }
+    div#contents.contents.local ul li {
+      counter-increment: toc-section;
+      background: none; // Remove bullets
+    }
+    div#contents.contents.local ul li a.reference:before {
+      content: counters(toc-section, ".") " ";
+    }
+
+    /* Automatic numbering for the body. */
+    body {
+      counter-reset: section subsection subsubsection;
+    }
+    .section h2 {
+      counter-reset: subsection subsubsection;
+      counter-increment: section;
+    }
+    .section h2 a.toc-backref:before {
+      content: counter(section) " ";
+    }
+    .section h3 {
+      counter-reset: subsubsection;
+      counter-increment: subsection;
+    }
+    .section h3 a.toc-backref:before {
+      content: counter(section) "." counter(subsection) " ";
+    }
+    .section h4 {
+      counter-increment: subsubsection;
+    }
+    .section h4 a.toc-backref:before {
+      content: counter(section) "." counter(subsection) "." counter(subsubsection) " ";
+    }
+  </style>
+
+.. 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 Mac OS X, and functions always pass objects at +0.  The
+    C-based APIs for Core Foundation objects, on the other hand, have much more
+    varied transfer semantics.
+
+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_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_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 a managed operation is performed on a ``__strong``
+or ``__weak`` object without a guarantee that it contains a primitive zero
+bit-pattern, or if the storage for such an object is freed or reused without the
+object being first assigned a null pointer.
+
+.. admonition:: Rationale
+
+  ARC cannot differentiate between an assignment operator which is intended to
+  "initialize" dynamic memory and one which is intended to potentially replace
+  a value.  Therefore the object's pointer must be valid before letting ARC at
+  it.  Similarly, C and Objective-C do not provide any language hooks for
+  destroying objects held in dynamic memory, so it is the programmer's
+  responsibility to avoid leaks (``__strong`` objects) and consistency errors
+  (``__weak`` objects).
+
+These requirements are followed automatically in Objective-C++ when creating
+objects of retainable object owner type with ``new`` or ``new[]`` and destroying
+them with ``delete``, ``delete[]``, or a pseudo-destructor expression.  Note
+that arrays of nontrivially-ownership-qualified type are not ABI compatible with
+non-ARC code because the element type is non-POD: such arrays that are
+``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.self:
+
+``self``
+--------
+
+The ``self`` parameter variable of an Objective-C method is never actually
+retained by the implementation.  It is undefined behavior, or at least
+dangerous, to cause an object to be deallocated during a message send to that
+object.
+
+To make this safe, for Objective-C instance methods ``self`` is implicitly
+``const`` unless the method is in the :ref:`init family
+<arc.family.semantics.init>`.  Further, ``self`` is **always** implicitly
+``const`` within a class method.
+
+.. 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 ``__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
+qualified with ``const __strong`` and objects encountered during the
+enumeration are not actually retained.
+
+.. 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:
+
+``id 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
+
+  id objc_storeStrong(id *object, id value) {
+    value = [value retain];
+    id oldValue = *object;
+    *object = value;
+    [oldValue release];
+    return value;
+  }
+
+Always returns ``value``.
+
+.. [*] 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/3.9.0/tools/clang/docs/_sources/Block-ABI-Apple.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/Block-ABI-Apple.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/Block-ABI-Apple.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/Block-ABI-Apple.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,935 @@
+==================================
+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 {
+        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 = {( .forwarding=&i, .flags=0, .size=sizeof(struct _block_byref_i) )};
+    struct __block_literal_5 _block_literal = {
+          &_NSConcreteStackBlock,
+          (1<<25)|(1<<29), <uninitialized>,
+          __block_invoke_5,
+          &__block_descriptor_5,
+          2,
+    };
+
+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_<appropo>);
+
+in the copy helper and:
+
+.. code-block:: c
+
+    _Block_object_dispose(->target, BLOCK_FIELD_<appropo>);
+
+in the dispose helper where ``<appropo>`` 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_<appropo>`` 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/3.9.0/tools/clang/docs/_sources/BlockLanguageSpec.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/BlockLanguageSpec.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/BlockLanguageSpec.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/BlockLanguageSpec.txt Fri Sep  2 10:56:46 2016
@@ -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/3.9.0/tools/clang/docs/_sources/ClangCheck.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangCheck.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangCheck.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangCheck.txt Fri Sep  2 10:56:46 2016
@@ -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 `clang-check` from search for a
+compilation database. For more information on how to setup and use `clang-check`
+in a project, see :doc:`HowToSetupToolingForLLVM`.

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangFormat.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangFormat.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangFormat.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangFormat.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,196 @@
+===========
+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++/Obj-C code.
+
+.. code-block:: console
+
+  $ clang-format -help
+  OVERVIEW: A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf 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}"
+
+  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.
+
+
+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.
+
+
+Visual Studio Integration
+=========================
+
+Download the latest Visual Studio extension from the `alpha build site
+<http://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
+
+
+Script for patch reformatting
+=============================
+
+The python script `clang/tools/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 HEAD^ | 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).

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

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangPlugins.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangPlugins.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangPlugins.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangPlugins.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,130 @@
+=============
+Clang Plugins
+=============
+
+Clang Plugins make it possible to run extra user defined actions during a
+compilation. This document will provide a basic walkthrough of how to write and
+run a Clang Plugin.
+
+Introduction
+============
+
+Clang Plugins run FrontendActions over code. See the :doc:`FrontendAction
+tutorial <RAVFrontendAction>` on how to write a ``FrontendAction`` using the
+``RecursiveASTVisitor``. In this tutorial, we'll demonstrate how to write a
+simple clang plugin.
+
+Writing a ``PluginASTAction``
+=============================
+
+The main difference from writing normal ``FrontendActions`` is that you can
+handle plugin command line options. The ``PluginASTAction`` base class declares
+a ``ParseArgs`` method which you have to implement in your plugin.
+
+.. code-block:: c++
+
+  bool ParseArgs(const CompilerInstance &CI,
+                 const std::vector<std::string>& args) {
+    for (unsigned i = 0, e = args.size(); i != e; ++i) {
+      if (args[i] == "-some-arg") {
+        // Handle the command line argument.
+      }
+    }
+    return true;
+  }
+
+Registering a plugin
+====================
+
+A plugin is loaded from a dynamic library at runtime by the compiler. To
+register a plugin in a library, use ``FrontendPluginRegistry::Add<>``:
+
+.. code-block:: c++
+
+  static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description");
+
+Defining pragmas
+================
+
+Plugins can also define pragmas by declaring a ``PragmaHandler`` and
+registering it using ``PragmaHandlerRegistry::Add<>``:
+
+.. code-block:: c++
+
+  // Define a pragma handler for #pragma example_pragma
+  class ExamplePragmaHandler : public PragmaHandler {
+  public:
+    ExamplePragmaHandler() : PragmaHandler("example_pragma") { }
+    void HandlePragma(Preprocessor &PP, PragmaIntroducerKind Introducer,
+                      Token &PragmaTok) {
+      // Handle the pragma
+    }
+  };
+
+  static PragmaHandlerRegistry::Add<ExamplePragmaHandler> Y("example_pragma","example pragma description");
+
+Putting it all together
+=======================
+
+Let's look at an example plugin that prints top-level function names.  This
+example is checked into the clang repository; please take a look at
+the `latest version of PrintFunctionNames.cpp
+<http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_.
+
+Running the plugin
+==================
+
+
+Using the cc1 command line
+--------------------------
+
+To run a plugin, the dynamic library containing the plugin registry must be
+loaded via the `-load` command line option. This will load all plugins
+that are registered, and you can select the plugins to run by specifying the
+`-plugin` option. Additional parameters for the plugins can be passed with
+`-plugin-arg-<plugin-name>`.
+
+Note that those options must reach clang's cc1 process. There are two
+ways to do so:
+
+* Directly call the parsing process by using the `-cc1` option; this
+  has the downside of not configuring the default header search paths, so
+  you'll need to specify the full system path configuration on the command
+  line.
+* Use clang as usual, but prefix all arguments to the cc1 process with
+  `-Xclang`.
+
+For example, to run the ``print-function-names`` plugin over a source file in
+clang, first build the plugin, and then call clang with the plugin from the
+source tree:
+
+.. code-block:: console
+
+  $ export BD=/path/to/build/directory
+  $ (cd $BD && make PrintFunctionNames )
+  $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \
+            -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \
+            -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \
+            tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \
+            -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \
+            -plugin -Xclang print-fns
+
+Also see the print-function-name plugin example's
+`README <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup>`_
+
+
+Using the clang command line
+----------------------------
+
+Using `-fplugin=plugin` on the clang command line passes the plugin
+through as an argument to `-load` on the cc1 command line. If the plugin
+class implements the ``getActionType`` method then the plugin is run
+automatically. For example, to run the plugin automatically after the main AST
+action (i.e. the same as using `-add-plugin`):
+
+.. code-block:: c++
+
+  // Automatically run the plugin after the main AST action
+  PluginASTAction::ActionType getActionType() override {
+    return AddAfterMainAction;
+  }

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangTools.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangTools.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangTools.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/ClangTools.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,167 @@
+========
+Overview
+========
+
+Clang Tools are standalone command line (and potentially GUI) tools
+designed for use by C++ developers who are already using and enjoying
+Clang as their compiler. These tools provide developer-oriented
+functionality such as fast syntax checking, automatic formatting,
+refactoring, etc.
+
+Only a couple of the most basic and fundamental tools are kept in the
+primary Clang Subversion project. The rest of the tools are kept in a
+side-project so that developers who don't want or need to build them
+don't. If you want to get access to the extra Clang Tools repository,
+simply check it out into the tools tree of your Clang checkout and
+follow the usual process for building and working with a combined
+LLVM/Clang checkout:
+
+-  With Subversion:
+
+   -  ``cd llvm/tools/clang/tools``
+   -  ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra``
+
+-  Or with Git:
+
+   -  ``cd llvm/tools/clang/tools``
+   -  ``git clone http://llvm.org/git/clang-tools-extra.git extra``
+
+This document describes a high-level overview of the organization of
+Clang Tools within the project as well as giving an introduction to some
+of the more important tools. However, it should be noted that this
+document is currently focused on Clang and Clang Tool developers, not on
+end users of these tools.
+
+Clang Tools Organization
+========================
+
+Clang Tools are CLI or GUI programs that are intended to be directly
+used by C++ developers. That is they are *not* primarily for use by
+Clang developers, although they are hopefully useful to C++ developers
+who happen to work on Clang, and we try to actively dogfood their
+functionality. They are developed in three components: the underlying
+infrastructure for building a standalone tool based on Clang, core
+shared logic used by many different tools in the form of refactoring and
+rewriting libraries, and the tools themselves.
+
+The underlying infrastructure for Clang Tools is the
+:doc:`LibTooling <LibTooling>` platform. See its documentation for much
+more detailed information about how this infrastructure works. The
+common refactoring and rewriting toolkit-style library is also part of
+LibTooling organizationally.
+
+A few Clang Tools are developed along side the core Clang libraries as
+examples and test cases of fundamental functionality. However, most of
+the tools are developed in a side repository to provide easy separation
+from the core libraries. We intentionally do not support public
+libraries in the side repository, as we want to carefully review and
+find good APIs for libraries as they are lifted out of a few tools and
+into the core Clang library set.
+
+Regardless of which repository Clang Tools' code resides in, the
+development process and practices for all Clang Tools are exactly those
+of Clang itself. They are entirely within the Clang *project*,
+regardless of the version control scheme.
+
+Core Clang Tools
+================
+
+The core set of Clang tools that are within the main repository are
+tools that very specifically complement, and allow use and testing of
+*Clang* specific functionality.
+
+``clang-check``
+---------------
+
+:doc:`ClangCheck` combines the LibTooling framework for running a
+Clang tool with the basic Clang diagnostics by syntax checking specific files
+in a fast, command line interface. It can also accept flags to re-display the
+diagnostics in different formats with different flags, suitable for use driving
+an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply
+fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for
+instructions on how to setup and used `clang-check`.
+
+``clang-format``
+----------------
+
+Clang-format is both a :doc:`library <LibFormat>` and a :doc:`stand-alone tool
+<ClangFormat>` with the goal of automatically reformatting C++ sources files
+according to configurable style guides.  To do so, clang-format uses Clang's
+``Lexer`` to transform an input file into a token stream and then changes all
+the whitespace around those tokens.  The goal is for clang-format to serve both
+as a user tool (ideally with powerful IDE integrations) and as part of other
+refactoring tools, e.g. to do a reformatting of all the lines changed during a
+renaming.
+
+
+Extra Clang Tools
+=================
+
+As various categories of Clang Tools are added to the extra repository,
+they'll be tracked here. The focus of this documentation is on the scope
+and features of the tools for other tool developers; each tool should
+provide its own user-focused documentation.
+
+``clang-tidy``
+--------------
+
+`clang-tidy <http://clang.llvm.org/extra/clang-tidy/>`_ is a clang-based C++
+linter tool. It provides an extensible framework for building compiler-based
+static analyses detecting and fixing bug-prone patterns, performance,
+portability and maintainability issues.
+
+
+Ideas for new Tools
+===================
+
+* C++ cast conversion tool.  Will convert C-style casts (``(type) value``) to
+  appropriate C++ cast (``static_cast``, ``const_cast`` or
+  ``reinterpret_cast``).
+* Non-member ``begin()`` and ``end()`` conversion tool.  Will convert
+  ``foo.begin()`` into ``begin(foo)`` and similarly for ``end()``, where
+  ``foo`` is a standard container.  We could also detect similar patterns for
+  arrays.
+* ``tr1`` removal tool.  Will migrate source code from using TR1 library
+  features to C++11 library.  For example:
+
+  .. code-block:: c++
+
+    #include <tr1/unordered_map>
+    int main()
+    {
+        std::tr1::unordered_map <int, int> ma;
+        std::cout << ma.size () << std::endl;
+        return 0;
+    }
+
+  should be rewritten to:
+
+  .. code-block:: c++
+
+    #include <unordered_map>
+    int main()
+    {
+        std::unordered_map <int, int> ma;
+        std::cout << ma.size () << std::endl;
+        return 0;
+    }
+
+* A tool to remove ``auto``.  Will convert ``auto`` to an explicit type or add
+  comments with deduced types.  The motivation is that there are developers
+  that don't want to use ``auto`` because they are afraid that they might lose
+  control over their code.
+
+* C++14: less verbose operator function objects (`N3421
+  <http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3421.htm>`_).
+  For example:
+
+  .. code-block:: c++
+
+    sort(v.begin(), v.end(), greater<ValueType>());
+
+  should be rewritten to:
+
+  .. code-block:: c++
+
+    sort(v.begin(), v.end(), greater<>());
+

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/CommandGuide/clang.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/CommandGuide/clang.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/CommandGuide/clang.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/CommandGuide/clang.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,506 @@
+clang - the Clang C, C++, and Objective-C compiler
+==================================================
+
+SYNOPSIS
+--------
+
+:program:`clang` [*options*] *filename ...*
+
+DESCRIPTION
+-----------
+
+:program:`clang` is a C, C++, and Objective-C compiler which encompasses
+preprocessing, parsing, optimization, code generation, assembly, and linking.
+Depending on which high-level mode setting is passed, Clang will stop before
+doing a full link.  While Clang is highly integrated, it is important to
+understand the stages of compilation, to understand how to invoke it.  These
+stages are:
+
+Driver
+    The clang executable is actually a small driver which controls the overall
+    execution of other tools such as the compiler, assembler and linker.
+    Typically you do not need to interact with the driver, but you
+    transparently use it to run the other tools.
+
+Preprocessing
+    This stage handles tokenization of the input source file, macro expansion,
+    #include expansion and handling of other preprocessor directives.  The
+    output of this stage is typically called a ".i" (for C), ".ii" (for C++),
+    ".mi" (for Objective-C), or ".mii" (for Objective-C++) file.
+
+Parsing and Semantic Analysis
+    This stage parses the input file, translating preprocessor tokens into a
+    parse tree.  Once in the form of a parse tree, it applies semantic
+    analysis to compute types for expressions as well and determine whether
+    the code is well formed. This stage is responsible for generating most of
+    the compiler warnings as well as parse errors. The output of this stage is
+    an "Abstract Syntax Tree" (AST).
+
+Code Generation and Optimization
+    This stage translates an AST into low-level intermediate code (known as
+    "LLVM IR") and ultimately to machine code.  This phase is responsible for
+    optimizing the generated code and handling target-specific code generation.
+    The output of this stage is typically called a ".s" file or "assembly" file.
+
+    Clang also supports the use of an integrated assembler, in which the code
+    generator produces object files directly. This avoids the overhead of
+    generating the ".s" file and of calling the target assembler.
+
+Assembler
+    This stage runs the target assembler to translate the output of the
+    compiler into a target object file. The output of this stage is typically
+    called a ".o" file or "object" file.
+
+Linker
+    This stage runs the target linker to merge multiple object files into an
+    executable or dynamic library. The output of this stage is typically called
+    an "a.out", ".dylib" or ".so" file.
+
+:program:`Clang Static Analyzer`
+
+The Clang Static Analyzer is a tool that scans source code to try to find bugs
+through code analysis.  This tool uses many parts of Clang and is built into
+the same driver.  Please see <http://clang-analyzer.llvm.org> for more details
+on how to use the static analyzer.
+
+OPTIONS
+-------
+
+Stage Selection Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. option:: -E
+
+ Run the preprocessor stage.
+
+.. option:: -fsyntax-only
+
+ Run the preprocessor, parser and type checking stages.
+
+.. option:: -S
+
+ Run the previous stages as well as LLVM generation and optimization stages
+ and target-specific code generation, producing an assembly file.
+
+.. option:: -c
+
+ Run all of the above, plus the assembler, generating a target ".o" object file.
+
+.. option:: no stage selection option
+
+ If no stage selection option is specified, all stages above are run, and the
+ linker is run to combine the results into an executable or shared library.
+
+Language Selection and Mode Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. option:: -x <language>
+
+ Treat subsequent input files as having type language.
+
+.. option:: -std=<language>
+
+ Specify the language standard to compile for.
+
+.. option:: -stdlib=<library>
+
+ Specify the C++ standard library to use; supported options are libstdc++ and
+ libc++.
+
+.. option:: -ansi
+
+ Same as -std=c89.
+
+.. option:: -ObjC, -ObjC++
+
+ Treat source input files as Objective-C and Object-C++ inputs respectively.
+
+.. option:: -trigraphs
+
+ Enable trigraphs.
+
+.. option:: -ffreestanding
+
+ Indicate that the file should be compiled for a freestanding, not a hosted,
+ environment.
+
+.. option:: -fno-builtin
+
+ Disable special handling and optimizations of builtin functions like
+ :c:func:`strlen` and :c:func:`malloc`.
+
+.. option:: -fmath-errno
+
+ Indicate that math functions should be treated as updating :c:data:`errno`.
+
+.. option:: -fpascal-strings
+
+ Enable support for Pascal-style strings with "\\pfoo".
+
+.. option:: -fms-extensions
+
+ Enable support for Microsoft extensions.
+
+.. option:: -fmsc-version=
+
+ Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise.
+
+.. option:: -fborland-extensions
+
+ Enable support for Borland extensions.
+
+.. option:: -fwritable-strings
+
+ Make all string literals default to writable.  This disables uniquing of
+ strings and other optimizations.
+
+.. option:: -flax-vector-conversions
+
+ Allow loose type checking rules for implicit vector conversions.
+
+.. option:: -fblocks
+
+ Enable the "Blocks" language feature.
+
+.. option:: -fobjc-gc-only
+
+ Indicate that Objective-C code should be compiled in GC-only mode, which only
+ works when Objective-C Garbage Collection is enabled.
+
+.. option:: -fobjc-gc
+
+ Indicate that Objective-C code should be compiled in hybrid-GC mode, which
+ works with both GC and non-GC mode.
+
+.. option:: -fobjc-abi-version=version
+
+ Select the Objective-C ABI version to use. Available versions are 1 (legacy
+ "fragile" ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2).
+
+.. option:: -fobjc-nonfragile-abi-version=<version>
+
+ Select the Objective-C non-fragile ABI version to use by default. This will
+ only be used as the Objective-C ABI when the non-fragile ABI is enabled
+ (either via :option:`-fobjc-nonfragile-abi`, or because it is the platform
+ default).
+
+.. option:: -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi
+
+ Enable use of the Objective-C non-fragile ABI. On platforms for which this is
+ the default ABI, it can be disabled with :option:`-fno-objc-nonfragile-abi`.
+
+Target Selection Options
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Clang fully supports cross compilation as an inherent part of its design.
+Depending on how your version of Clang is configured, it may have support for a
+number of cross compilers, or may only support a native target.
+
+.. option:: -arch <architecture>
+
+  Specify the architecture to build for.
+
+.. option:: -mmacosx-version-min=<version>
+
+  When building for Mac OS X, specify the minimum version supported by your
+  application.
+
+.. option:: -miphoneos-version-min
+
+  When building for iPhone OS, specify the minimum version supported by your
+  application.
+
+.. option:: -march=<cpu>
+
+  Specify that Clang should generate code for a specific processor family
+  member and later.  For example, if you specify -march=i486, the compiler is
+  allowed to generate instructions that are valid on i486 and later processors,
+  but which may not exist on earlier ones.
+
+
+Code Generation Options
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. option:: -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -O, -O4
+
+  Specify which optimization level to use:
+
+    :option:`-O0` Means "no optimization": this level compiles the fastest and
+    generates the most debuggable code.
+
+    :option:`-O1` Somewhere between :option:`-O0` and :option:`-O2`.
+
+    :option:`-O2` Moderate level of optimization which enables most
+    optimizations.
+
+    :option:`-O3` Like :option:`-O2`, except that it enables optimizations that
+    take longer to perform or that may generate larger code (in an attempt to
+    make the program run faster).
+
+    :option:`-Ofast` Enables all the optimizations from :option:`-O3` along
+    with other aggressive optimizations that may violate strict compliance with
+    language standards.
+
+    :option:`-Os` Like :option:`-O2` with extra optimizations to reduce code
+    size.
+
+    :option:`-Oz` Like :option:`-Os` (and thus :option:`-O2`), but reduces code
+    size further.
+
+    :option:`-O` Equivalent to :option:`-O2`.
+
+    :option:`-O4` and higher
+
+      Currently equivalent to :option:`-O3`
+
+.. option:: -g, -gline-tables-only, -gmodules
+
+  Control debug information output.  Note that Clang debug information works
+  best at :option:`-O0`.  When more than one option starting with `-g` is
+  specified, the last one wins:
+
+    :option:`-g` Generate debug information.
+
+    :option:`-gline-tables-only` Generate only line table debug information. This
+    allows for symbolicated backtraces with inlining information, but does not
+    include any information about variables, their locations or types.
+
+    :option:`-gmodules` Generate debug information that contains external
+    references to types defined in Clang modules or precompiled headers instead
+    of emitting redundant debug type information into every object file.  This
+    option transparently switches the Clang module format to object file
+    containers that hold the Clang module together with the debug information.
+    When compiling a program that uses Clang modules or precompiled headers,
+    this option produces complete debug information with faster compile
+    times and much smaller object files.
+
+    This option should not be used when building static libraries for
+    distribution to other machines because the debug info will contain
+    references to the module cache on the machine the object files in the
+    library were built on.
+
+.. option:: -fstandalone-debug -fno-standalone-debug
+
+  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.
+
+  The :option:`-fstandalone-debug` option turns off these optimizations.
+  This is useful when working with 3rd-party libraries that don't come with
+  debug information.  This is the default on Darwin.  Note that Clang will
+  never emit type information for types that are not referenced at all by the
+  program.
+
+.. option:: -fexceptions
+
+  Enable generation of unwind information. This allows exceptions to be thrown
+  through Clang compiled stack frames.  This is on by default in x86-64.
+
+.. option:: -ftrapv
+
+  Generate code to catch integer overflow errors.  Signed integer overflow is
+  undefined in C. With this flag, extra code is generated to detect this and
+  abort when it happens.
+
+.. option:: -fvisibility
+
+  This flag sets the default visibility level.
+
+.. option:: -fcommon, -fno-common
+
+  This flag specifies that variables without initializers get common linkage.
+  It can be disabled with :option:`-fno-common`.
+
+.. option:: -ftls-model=<model>
+
+  Set the default thread-local storage (TLS) model to use for thread-local
+  variables. Valid values are: "global-dynamic", "local-dynamic",
+  "initial-exec" and "local-exec". The default is "global-dynamic". The default
+  model can be overridden with the tls_model attribute. The compiler will try
+  to choose a more efficient model if possible.
+
+.. option:: -flto, -emit-llvm
+
+  Generate output files in LLVM formats, suitable for link time optimization.
+  When used with :option:`-S` this generates LLVM intermediate language
+  assembly files, otherwise this generates LLVM bitcode format object files
+  (which may be passed to the linker depending on the stage selection options).
+
+Driver Options
+~~~~~~~~~~~~~~
+
+.. option:: -###
+
+  Print (but do not run) the commands to run for this compilation.
+
+.. option:: --help
+
+  Display available options.
+
+.. option:: -Qunused-arguments
+
+  Do not emit any warnings for unused driver arguments.
+
+.. option:: -Wa,<args>
+
+  Pass the comma separated arguments in args to the assembler.
+
+.. option:: -Wl,<args>
+
+  Pass the comma separated arguments in args to the linker.
+
+.. option:: -Wp,<args>
+
+  Pass the comma separated arguments in args to the preprocessor.
+
+.. option:: -Xanalyzer <arg>
+
+  Pass arg to the static analyzer.
+
+.. option:: -Xassembler <arg>
+
+  Pass arg to the assembler.
+
+.. option:: -Xlinker <arg>
+
+  Pass arg to the linker.
+
+.. option:: -Xpreprocessor <arg>
+
+  Pass arg to the preprocessor.
+
+.. option:: -o <file>
+
+  Write output to file.
+
+.. option:: -print-file-name=<file>
+
+  Print the full library path of file.
+
+.. option:: -print-libgcc-file-name
+
+  Print the library path for "libgcc.a".
+
+.. option:: -print-prog-name=<name>
+
+  Print the full program path of name.
+
+.. option:: -print-search-dirs
+
+  Print the paths used for finding libraries and programs.
+
+.. option:: -save-temps
+
+  Save intermediate compilation results.
+
+.. option:: -integrated-as, -no-integrated-as
+
+  Used to enable and disable, respectively, the use of the integrated
+  assembler. Whether the integrated assembler is on by default is target
+  dependent.
+
+.. option:: -time
+
+  Time individual commands.
+
+.. option:: -ftime-report
+
+  Print timing summary of each stage of compilation.
+
+.. option:: -v
+
+  Show commands to run and use verbose output.
+
+
+Diagnostics Options
+~~~~~~~~~~~~~~~~~~~
+
+.. option:: -fshow-column, -fshow-source-location, -fcaret-diagnostics, -fdiagnostics-fixit-info, -fdiagnostics-parseable-fixits, -fdiagnostics-print-source-range-info, -fprint-source-range-info, -fdiagnostics-show-option, -fmessage-length
+
+  These options control how Clang prints out information about diagnostics
+  (errors and warnings). Please see the Clang User's Manual for more information.
+
+Preprocessor Options
+~~~~~~~~~~~~~~~~~~~~
+
+.. option:: -D<macroname>=<value>
+
+  Adds an implicit #define into the predefines buffer which is read before the
+  source file is preprocessed.
+
+.. option:: -U<macroname>
+
+  Adds an implicit #undef into the predefines buffer which is read before the
+  source file is preprocessed.
+
+.. option:: -include <filename>
+
+  Adds an implicit #include into the predefines buffer which is read before the
+  source file is preprocessed.
+
+.. option:: -I<directory>
+
+  Add the specified directory to the search path for include files.
+
+.. option:: -F<directory>
+
+  Add the specified directory to the search path for framework include files.
+
+.. option:: -nostdinc
+
+  Do not search the standard system directories or compiler builtin directories
+  for include files.
+
+.. option:: -nostdlibinc
+
+  Do not search the standard system directories for include files, but do
+  search compiler builtin include directories.
+
+.. option:: -nobuiltininc
+
+  Do not search clang's builtin directory for include files.
+
+
+ENVIRONMENT
+-----------
+
+.. envvar:: TMPDIR, TEMP, TMP
+
+  These environment variables are checked, in order, for the location to write
+  temporary files used during the compilation process.
+
+.. envvar:: CPATH
+
+  If this environment variable is present, it is treated as a delimited list of
+  paths to be added to the default system include path list. The delimiter is
+  the platform dependent delimiter, as used in the PATH environment variable.
+
+  Empty components in the environment variable are ignored.
+
+.. envvar:: C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH
+
+  These environment variables specify additional paths, as for :envvar:`CPATH`, which are
+  only used when processing the appropriate language.
+
+.. envvar:: MACOSX_DEPLOYMENT_TARGET
+
+  If :option:`-mmacosx-version-min` is unspecified, the default deployment
+  target is read from this environment variable. This option only affects
+  Darwin targets.
+
+BUGS
+----
+
+To report bugs, please visit <http://llvm.org/bugs/>.  Most bug reports should
+include preprocessed source files (use the :option:`-E` option) and the full
+output of the compiler, along with information to reproduce.
+
+SEE ALSO
+--------
+
+:manpage:`as(1)`, :manpage:`ld(1)`
+

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/CommandGuide/index.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/CommandGuide/index.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/CommandGuide/index.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/CommandGuide/index.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,17 @@
+Clang "man" pages
+-----------------
+
+The following documents are command descriptions for all of the Clang tools.
+These pages describe how to use the Clang commands and what their options are.
+Note that these pages do not describe all of the options available for all
+tools. To get a complete listing, pass the ``--help`` (general options) or
+``--help-hidden`` (general and debugging options) arguments to the tool you are
+interested in.
+
+Basic Commands
+~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   clang

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/ControlFlowIntegrity.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/ControlFlowIntegrity.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/ControlFlowIntegrity.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/ControlFlowIntegrity.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,286 @@
+======================
+Control Flow Integrity
+======================
+
+.. toctree::
+   :hidden:
+
+   ControlFlowIntegrityDesign
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+Clang includes an implementation of a number of control flow integrity (CFI)
+schemes, which are designed to abort the program upon detecting certain forms
+of undefined behavior that can potentially allow attackers to subvert the
+program's control flow. These schemes have been optimized for performance,
+allowing developers to enable them in release builds.
+
+To enable Clang's available CFI schemes, use the flag ``-fsanitize=cfi``.
+You can also enable a subset of available :ref:`schemes <cfi-schemes>`.
+As currently implemented, all schemes rely on link-time optimization (LTO);
+so it is required to specify ``-flto``, and the linker used must support LTO,
+for example via the `gold plugin`_.
+
+To allow the checks to be implemented efficiently, the program must
+be structured such that certain object files are compiled with CFI
+enabled, and are statically linked into the program. This may preclude
+the use of shared libraries in some cases.
+
+The compiler will only produce CFI checks for a class if it can infer hidden
+LTO visibility for that class. LTO visibility is a property of a class that
+is inferred from flags and attributes. For more details, see the documentation
+for :doc:`LTO visibility <LTOVisibility>`.
+
+The ``-fsanitize=cfi-{vcall,nvcall,derived-cast,unrelated-cast}`` flags
+require that a ``-fvisibility=`` flag also be specified. This is because the
+default visibility setting is ``-fvisibility=default``, which would disable
+CFI checks for classes without visibility attributes. Most users will want
+to specify ``-fvisibility=hidden``, which enables CFI checks for such classes.
+
+Experimental support for :ref:`cross-DSO control flow integrity
+<cfi-cross-dso>` exists that does not require classes to have hidden LTO
+visibility. This cross-DSO support has unstable ABI at this time.
+
+.. _gold plugin: http://llvm.org/docs/GoldPlugin.html
+
+.. _cfi-schemes:
+
+Available schemes
+=================
+
+Available schemes are:
+
+  -  ``-fsanitize=cfi-cast-strict``: Enables :ref:`strict cast checks
+     <cfi-strictness>`.
+  -  ``-fsanitize=cfi-derived-cast``: Base-to-derived cast to the wrong
+     dynamic type.
+  -  ``-fsanitize=cfi-unrelated-cast``: Cast from ``void*`` or another
+     unrelated type to the wrong dynamic type.
+  -  ``-fsanitize=cfi-nvcall``: Non-virtual call via an object whose vptr is of
+     the wrong dynamic type.
+  -  ``-fsanitize=cfi-vcall``: Virtual call via an object whose vptr is of the
+     wrong dynamic type.
+  -  ``-fsanitize=cfi-icall``: Indirect call of a function with wrong dynamic
+     type.
+
+You can use ``-fsanitize=cfi`` to enable all the schemes and use
+``-fno-sanitize`` flag to narrow down the set of schemes as desired.
+For example, you can build your program with
+``-fsanitize=cfi -fno-sanitize=cfi-nvcall,cfi-icall``
+to use all schemes except for non-virtual member function call and indirect call
+checking.
+
+Remember that you have to provide ``-flto`` if at least one CFI scheme is
+enabled.
+
+Trapping and Diagnostics
+========================
+
+By default, CFI will abort the program immediately upon detecting a control
+flow integrity violation. You can use the :ref:`-fno-sanitize-trap=
+<controlling-code-generation>` flag to cause CFI to print a diagnostic
+similar to the one below before the program aborts.
+
+.. code-block:: console
+
+    bad-cast.cpp:109:7: runtime error: control flow integrity check for type 'B' failed during base-to-derived cast (vtable address 0x000000425a50)
+    0x000000425a50: note: vtable is of type 'A'
+     00 00 00 00  f0 f1 41 00 00 00 00 00  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  20 5a 42 00
+                  ^ 
+
+If diagnostics are enabled, you can also configure CFI to continue program
+execution instead of aborting by using the :ref:`-fsanitize-recover=
+<controlling-code-generation>` flag.
+
+Forward-Edge CFI for Virtual Calls
+==================================
+
+This scheme checks that virtual calls take place using a vptr of the correct
+dynamic type; that is, the dynamic type of the called object must be a
+derived class of the static type of the object used to make the call.
+This CFI scheme can be enabled on its own using ``-fsanitize=cfi-vcall``.
+
+For this scheme to work, all translation units containing the definition
+of a virtual member function (whether inline or not), other than members
+of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with
+``-fsanitize=cfi-vcall`` enabled and be statically linked into the program.
+
+Performance
+-----------
+
+A performance overhead of less than 1% has been measured by running the
+Dromaeo benchmark suite against an instrumented version of the Chromium
+web browser. Another good performance benchmark for this mechanism is the
+virtual-call-heavy SPEC 2006 xalancbmk.
+
+Note that this scheme has not yet been optimized for binary size; an increase
+of up to 15% has been observed for Chromium.
+
+Bad Cast Checking
+=================
+
+This scheme checks that pointer casts are made to an object of the correct
+dynamic type; that is, the dynamic type of the object must be a derived class
+of the pointee type of the cast. The checks are currently only introduced
+where the class being casted to is a polymorphic class.
+
+Bad casts are not in themselves control flow integrity violations, but they
+can also create security vulnerabilities, and the implementation uses many
+of the same mechanisms.
+
+There are two types of bad cast that may be forbidden: bad casts
+from a base class to a derived class (which can be checked with
+``-fsanitize=cfi-derived-cast``), and bad casts from a pointer of
+type ``void*`` or another unrelated type (which can be checked with
+``-fsanitize=cfi-unrelated-cast``).
+
+The difference between these two types of casts is that the first is defined
+by the C++ standard to produce an undefined value, while the second is not
+in itself undefined behavior (it is well defined to cast the pointer back
+to its original type) unless the object is uninitialized and the cast is a
+``static_cast`` (see C++14 [basic.life]p5).
+
+If a program as a matter of policy forbids the second type of cast, that
+restriction can normally be enforced. However it may in some cases be necessary
+for a function to perform a forbidden cast to conform with an external API
+(e.g. the ``allocate`` member function of a standard library allocator). Such
+functions may be :ref:`blacklisted <cfi-blacklist>`.
+
+For this scheme to work, all translation units containing the definition
+of a virtual member function (whether inline or not), other than members
+of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with
+``-fsanitize=cfi-derived-cast`` or ``-fsanitize=cfi-unrelated-cast`` enabled
+and be statically linked into the program.
+
+Non-Virtual Member Function Call Checking
+=========================================
+
+This scheme checks that non-virtual calls take place using an object of
+the correct dynamic type; that is, the dynamic type of the called object
+must be a derived class of the static type of the object used to make the
+call. The checks are currently only introduced where the object is of a
+polymorphic class type.  This CFI scheme can be enabled on its own using
+``-fsanitize=cfi-nvcall``.
+
+For this scheme to work, all translation units containing the definition
+of a virtual member function (whether inline or not), other than members
+of :ref:`blacklisted <cfi-blacklist>` types, must be compiled with
+``-fsanitize=cfi-nvcall`` enabled and be statically linked into the program.
+
+.. _cfi-strictness:
+
+Strictness
+----------
+
+If a class has a single non-virtual base and does not introduce or override
+virtual member functions or fields other than an implicitly defined virtual
+destructor, it will have the same layout and virtual function semantics as
+its base. By default, casts to such classes are checked as if they were made
+to the least derived such class.
+
+Casting an instance of a base class to such a derived class is technically
+undefined behavior, but it is a relatively common hack for introducing
+member functions on class instances with specific properties that works under
+most compilers and should not have security implications, so we allow it by
+default. It can be disabled with ``-fsanitize=cfi-cast-strict``.
+
+Indirect Function Call Checking
+===============================
+
+This scheme checks that function calls take place using a function of the
+correct dynamic type; that is, the dynamic type of the function must match
+the static type used at the call. This CFI scheme can be enabled on its own
+using ``-fsanitize=cfi-icall``.
+
+For this scheme to work, each indirect function call in the program, other
+than calls in :ref:`blacklisted <cfi-blacklist>` functions, must call a
+function which was either compiled with ``-fsanitize=cfi-icall`` enabled,
+or whose address was taken by a function in a translation unit compiled with
+``-fsanitize=cfi-icall``.
+
+If a function in a translation unit compiled with ``-fsanitize=cfi-icall``
+takes the address of a function not compiled with ``-fsanitize=cfi-icall``,
+that address may differ from the address taken by a function in a translation
+unit not compiled with ``-fsanitize=cfi-icall``. This is technically a
+violation of the C and C++ standards, but it should not affect most programs.
+
+Each translation unit compiled with ``-fsanitize=cfi-icall`` must be
+statically linked into the program or shared library, and calls across
+shared library boundaries are handled as if the callee was not compiled with
+``-fsanitize=cfi-icall``.
+
+This scheme is currently only supported on the x86 and x86_64 architectures.
+
+``-fsanitize=cfi-icall`` and ``-fsanitize=function``
+----------------------------------------------------
+
+This tool is similar to ``-fsanitize=function`` in that both tools check
+the types of function calls. However, the two tools occupy different points
+on the design space; ``-fsanitize=function`` is a developer tool designed
+to find bugs in local development builds, whereas ``-fsanitize=cfi-icall``
+is a security hardening mechanism designed to be deployed in release builds.
+
+``-fsanitize=function`` has a higher space and time overhead due to a more
+complex type check at indirect call sites, as well as a need for run-time
+type information (RTTI), which may make it unsuitable for deployment. Because
+of the need for RTTI, ``-fsanitize=function`` can only be used with C++
+programs, whereas ``-fsanitize=cfi-icall`` can protect both C and C++ programs.
+
+On the other hand, ``-fsanitize=function`` conforms more closely with the C++
+standard and user expectations around interaction with shared libraries;
+the identity of function pointers is maintained, and calls across shared
+library boundaries are no different from calls within a single program or
+shared library.
+
+.. _cfi-blacklist:
+
+Blacklist
+=========
+
+A :doc:`SanitizerSpecialCaseList` can be used to relax CFI checks for certain
+source files, functions and types using the ``src``, ``fun`` and ``type``
+entity types.
+
+.. code-block:: bash
+
+    # Suppress checking for code in a file.
+    src:bad_file.cpp
+    src:bad_header.h
+    # Ignore all functions with names containing MyFooBar.
+    fun:*MyFooBar*
+    # Ignore all types in the standard library.
+    type:std::*
+
+.. _cfi-cross-dso:
+
+Shared library support
+======================
+
+Use **-f[no-]sanitize-cfi-cross-dso** to enable the cross-DSO control
+flow integrity mode, which allows all CFI schemes listed above to
+apply across DSO boundaries. As in the regular CFI, each DSO must be
+built with ``-flto``.
+
+Normally, CFI checks will only be performed for classes that have hidden LTO
+visibility. With this flag enabled, the compiler will emit cross-DSO CFI
+checks for all classes, except for those which appear in the CFI blacklist
+or which use a ``no_sanitize`` attribute.
+
+Design
+======
+
+Please refer to the :doc:`design document<ControlFlowIntegrityDesign>`.
+
+Publications
+============
+
+`Control-Flow Integrity: Principles, Implementations, and Applications <http://research.microsoft.com/pubs/64250/ccs05.pdf>`_.
+Martin Abadi, Mihai Budiu, Úlfar Erlingsson, Jay Ligatti.
+
+`Enforcing Forward-Edge Control-Flow Integrity in GCC & LLVM <http://www.pcc.me.uk/~peter/acad/usenix14.pdf>`_.
+Caroline Tice, Tom Roeder, Peter Collingbourne, Stephen Checkoway,
+Úlfar Erlingsson, Luis Lozano, Geoff Pike.

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,499 @@
+===========================================
+Control Flow Integrity Design Documentation
+===========================================
+
+This page documents the design of the :doc:`ControlFlowIntegrity` schemes
+supported by Clang.
+
+Forward-Edge CFI for Virtual Calls
+==================================
+
+This scheme works by allocating, for each static type used to make a virtual
+call, a region of read-only storage in the object file holding a bit vector
+that maps onto to the region of storage used for those virtual tables. Each
+set bit in the bit vector corresponds to the `address point`_ for a virtual
+table compatible with the static type for which the bit vector is being built.
+
+For example, consider the following three C++ classes:
+
+.. code-block:: c++
+
+  struct A {
+    virtual void f1();
+    virtual void f2();
+    virtual void f3();
+  };
+
+  struct B : A {
+    virtual void f1();
+    virtual void f2();
+    virtual void f3();
+  };
+
+  struct C : A {
+    virtual void f1();
+    virtual void f2();
+    virtual void f3();
+  };
+
+The scheme will cause the virtual tables for A, B and C to be laid out
+consecutively:
+
+.. csv-table:: Virtual Table Layout for A, B, C
+  :header: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
+
+  A::offset-to-top, &A::rtti, &A::f1, &A::f2, &A::f3, B::offset-to-top, &B::rtti, &B::f1, &B::f2, &B::f3, C::offset-to-top, &C::rtti, &C::f1, &C::f2, &C::f3
+
+The bit vector for static types A, B and C will look like this:
+
+.. csv-table:: Bit Vectors for A, B, C
+  :header: Class, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
+
+  A, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0
+  B, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0
+  C, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0
+
+Bit vectors are represented in the object file as byte arrays. By loading
+from indexed offsets into the byte array and applying a mask, a program can
+test bits from the bit set with a relatively short instruction sequence. Bit
+vectors may overlap so long as they use different bits. For the full details,
+see the `ByteArrayBuilder`_ class.
+
+In this case, assuming A is laid out at offset 0 in bit 0, B at offset 0 in
+bit 1 and C at offset 0 in bit 2, the byte array would look like this:
+
+.. code-block:: c++
+
+  char bits[] = { 0, 0, 1, 0, 0, 0, 3, 0, 0, 0, 0, 5, 0, 0 };
+
+To emit a virtual call, the compiler will assemble code that checks that
+the object's virtual table pointer is in-bounds and aligned and that the
+relevant bit is set in the bit vector.
+
+For example on x86 a typical virtual call may look like this:
+
+.. code-block:: none
+
+  ca7fbb:       48 8b 0f                mov    (%rdi),%rcx
+  ca7fbe:       48 8d 15 c3 42 fb 07    lea    0x7fb42c3(%rip),%rdx
+  ca7fc5:       48 89 c8                mov    %rcx,%rax
+  ca7fc8:       48 29 d0                sub    %rdx,%rax
+  ca7fcb:       48 c1 c0 3d             rol    $0x3d,%rax
+  ca7fcf:       48 3d 7f 01 00 00       cmp    $0x17f,%rax
+  ca7fd5:       0f 87 36 05 00 00       ja     ca8511
+  ca7fdb:       48 8d 15 c0 0b f7 06    lea    0x6f70bc0(%rip),%rdx
+  ca7fe2:       f6 04 10 10             testb  $0x10,(%rax,%rdx,1)
+  ca7fe6:       0f 84 25 05 00 00       je     ca8511
+  ca7fec:       ff 91 98 00 00 00       callq  *0x98(%rcx)
+    [...]
+  ca8511:       0f 0b                   ud2
+
+The compiler relies on co-operation from the linker in order to assemble
+the bit vectors for the whole program. It currently does this using LLVM's
+`type metadata`_ mechanism together with link-time optimization.
+
+.. _address point: https://mentorembedded.github.io/cxx-abi/abi.html#vtable-general
+.. _type metadata: http://llvm.org/docs/TypeMetadata.html
+.. _ByteArrayBuilder: http://llvm.org/docs/doxygen/html/structllvm_1_1ByteArrayBuilder.html
+
+Optimizations
+-------------
+
+The scheme as described above is the fully general variant of the scheme.
+Most of the time we are able to apply one or more of the following
+optimizations to improve binary size or performance.
+
+In fact, if you try the above example with the current version of the
+compiler, you will probably find that it will not use the described virtual
+table layout or machine instructions. Some of the optimizations we are about
+to introduce cause the compiler to use a different layout or a different
+sequence of machine instructions.
+
+Stripping Leading/Trailing Zeros in Bit Vectors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a bit vector contains leading or trailing zeros, we can strip them from
+the vector. The compiler will emit code to check if the pointer is in range
+of the region covered by ones, and perform the bit vector check using a
+truncated version of the bit vector. For example, the bit vectors for our
+example class hierarchy will be emitted like this:
+
+.. csv-table:: Bit Vectors for A, B, C
+  :header: Class, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
+
+  A,  ,  , 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1,  ,  
+  B,  ,  ,  ,  ,  ,  ,  , 1,  ,  ,  ,  ,  ,  ,  
+  C,  ,  ,  ,  ,  ,  ,  ,  ,  ,  ,  ,  , 1,  ,  
+
+Short Inline Bit Vectors
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the vector is sufficiently short, we can represent it as an inline constant
+on x86. This saves us a few instructions when reading the correct element
+of the bit vector.
+
+If the bit vector fits in 32 bits, the code looks like this:
+
+.. code-block:: none
+
+     dc2:       48 8b 03                mov    (%rbx),%rax
+     dc5:       48 8d 15 14 1e 00 00    lea    0x1e14(%rip),%rdx
+     dcc:       48 89 c1                mov    %rax,%rcx
+     dcf:       48 29 d1                sub    %rdx,%rcx
+     dd2:       48 c1 c1 3d             rol    $0x3d,%rcx
+     dd6:       48 83 f9 03             cmp    $0x3,%rcx
+     dda:       77 2f                   ja     e0b <main+0x9b>
+     ddc:       ba 09 00 00 00          mov    $0x9,%edx
+     de1:       0f a3 ca                bt     %ecx,%edx
+     de4:       73 25                   jae    e0b <main+0x9b>
+     de6:       48 89 df                mov    %rbx,%rdi
+     de9:       ff 10                   callq  *(%rax)
+    [...]
+     e0b:       0f 0b                   ud2    
+
+Or if the bit vector fits in 64 bits:
+
+.. code-block:: none
+
+    11a6:       48 8b 03                mov    (%rbx),%rax
+    11a9:       48 8d 15 d0 28 00 00    lea    0x28d0(%rip),%rdx
+    11b0:       48 89 c1                mov    %rax,%rcx
+    11b3:       48 29 d1                sub    %rdx,%rcx
+    11b6:       48 c1 c1 3d             rol    $0x3d,%rcx
+    11ba:       48 83 f9 2a             cmp    $0x2a,%rcx
+    11be:       77 35                   ja     11f5 <main+0xb5>
+    11c0:       48 ba 09 00 00 00 00    movabs $0x40000000009,%rdx
+    11c7:       04 00 00 
+    11ca:       48 0f a3 ca             bt     %rcx,%rdx
+    11ce:       73 25                   jae    11f5 <main+0xb5>
+    11d0:       48 89 df                mov    %rbx,%rdi
+    11d3:       ff 10                   callq  *(%rax)
+    [...]
+    11f5:       0f 0b                   ud2    
+
+If the bit vector consists of a single bit, there is only one possible
+virtual table, and the check can consist of a single equality comparison:
+
+.. code-block:: none
+
+     9a2:   48 8b 03                mov    (%rbx),%rax
+     9a5:   48 8d 0d a4 13 00 00    lea    0x13a4(%rip),%rcx
+     9ac:   48 39 c8                cmp    %rcx,%rax
+     9af:   75 25                   jne    9d6 <main+0x86>
+     9b1:   48 89 df                mov    %rbx,%rdi
+     9b4:   ff 10                   callq  *(%rax)
+     [...]
+     9d6:   0f 0b                   ud2
+
+Virtual Table Layout
+~~~~~~~~~~~~~~~~~~~~
+
+The compiler lays out classes of disjoint hierarchies in separate regions
+of the object file. At worst, bit vectors in disjoint hierarchies only
+need to cover their disjoint hierarchy. But the closer that classes in
+sub-hierarchies are laid out to each other, the smaller the bit vectors for
+those sub-hierarchies need to be (see "Stripping Leading/Trailing Zeros in Bit
+Vectors" above). The `GlobalLayoutBuilder`_ class is responsible for laying
+out the globals efficiently to minimize the sizes of the underlying bitsets.
+
+.. _GlobalLayoutBuilder: http://llvm.org/viewvc/llvm-project/llvm/trunk/include/llvm/Transforms/IPO/LowerTypeTests.h?view=markup
+
+Alignment
+~~~~~~~~~
+
+If all gaps between address points in a particular bit vector are multiples
+of powers of 2, the compiler can compress the bit vector by strengthening
+the alignment requirements of the virtual table pointer. For example, given
+this class hierarchy:
+
+.. code-block:: c++
+
+  struct A {
+    virtual void f1();
+    virtual void f2();
+  };
+
+  struct B : A {
+    virtual void f1();
+    virtual void f2();
+    virtual void f3();
+    virtual void f4();
+    virtual void f5();
+    virtual void f6();
+  };
+
+  struct C : A {
+    virtual void f1();
+    virtual void f2();
+  };
+
+The virtual tables will be laid out like this:
+
+.. csv-table:: Virtual Table Layout for A, B, C
+  :header: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
+
+  A::offset-to-top, &A::rtti, &A::f1, &A::f2, B::offset-to-top, &B::rtti, &B::f1, &B::f2, &B::f3, &B::f4, &B::f5, &B::f6, C::offset-to-top, &C::rtti, &C::f1, &C::f2
+
+Notice that each address point for A is separated by 4 words. This lets us
+emit a compressed bit vector for A that looks like this:
+
+.. csv-table::
+  :header: 2, 6, 10, 14
+
+  1, 1, 0, 1
+
+At call sites, the compiler will strengthen the alignment requirements by
+using a different rotate count. For example, on a 64-bit machine where the
+address points are 4-word aligned (as in A from our example), the ``rol``
+instruction may look like this:
+
+.. code-block:: none
+
+     dd2:       48 c1 c1 3b             rol    $0x3b,%rcx
+
+Padding to Powers of 2
+~~~~~~~~~~~~~~~~~~~~~~
+
+Of course, this alignment scheme works best if the address points are
+in fact aligned correctly. To make this more likely to happen, we insert
+padding between virtual tables that in many cases aligns address points to
+a power of 2. Specifically, our padding aligns virtual tables to the next
+highest power of 2 bytes; because address points for specific base classes
+normally appear at fixed offsets within the virtual table, this normally
+has the effect of aligning the address points as well.
+
+This scheme introduces tradeoffs between decreased space overhead for
+instructions and bit vectors and increased overhead in the form of padding. We
+therefore limit the amount of padding so that we align to no more than 128
+bytes. This number was found experimentally to provide a good tradeoff.
+
+Eliminating Bit Vector Checks for All-Ones Bit Vectors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the bit vector is all ones, the bit vector check is redundant; we simply
+need to check that the address is in range and well aligned. This is more
+likely to occur if the virtual tables are padded.
+
+Forward-Edge CFI for Indirect Function Calls
+============================================
+
+Under forward-edge CFI for indirect function calls, each unique function
+type has its own bit vector, and at each call site we need to check that the
+function pointer is a member of the function type's bit vector. This scheme
+works in a similar way to forward-edge CFI for virtual calls, the distinction
+being that we need to build bit vectors of function entry points rather than
+of virtual tables.
+
+Unlike when re-arranging global variables, we cannot re-arrange functions
+in a particular order and base our calculations on the layout of the
+functions' entry points, as we have no idea how large a particular function
+will end up being (the function sizes could even depend on how we arrange
+the functions). Instead, we build a jump table, which is a block of code
+consisting of one branch instruction for each of the functions in the bit
+set that branches to the target function, and redirect any taken function
+addresses to the corresponding jump table entry. In this way, the distance
+between function entry points is predictable and controllable. In the object
+file's symbol table, the symbols for the target functions also refer to the
+jump table entries, so that addresses taken outside the module will pass
+any verification done inside the module.
+
+In more concrete terms, suppose we have three functions ``f``, ``g``,
+``h`` which are all of the same type, and a function foo that returns their
+addresses:
+
+.. code-block:: none
+
+  f:
+  mov 0, %eax
+  ret
+
+  g:
+  mov 1, %eax
+  ret
+
+  h:
+  mov 2, %eax
+  ret
+
+  foo:
+  mov f, %eax
+  mov g, %edx
+  mov h, %ecx
+  ret
+
+Our jump table will (conceptually) look like this:
+
+.. code-block:: none
+
+  f:
+  jmp .Ltmp0 ; 5 bytes
+  int3       ; 1 byte
+  int3       ; 1 byte
+  int3       ; 1 byte
+
+  g:
+  jmp .Ltmp1 ; 5 bytes
+  int3       ; 1 byte
+  int3       ; 1 byte
+  int3       ; 1 byte
+
+  h:
+  jmp .Ltmp2 ; 5 bytes
+  int3       ; 1 byte
+  int3       ; 1 byte
+  int3       ; 1 byte
+
+  .Ltmp0:
+  mov 0, %eax
+  ret
+
+  .Ltmp1:
+  mov 1, %eax
+  ret
+
+  .Ltmp2:
+  mov 2, %eax
+  ret
+
+  foo:
+  mov f, %eax
+  mov g, %edx
+  mov h, %ecx
+  ret
+
+Because the addresses of ``f``, ``g``, ``h`` are evenly spaced at a power of
+2, and function types do not overlap (unlike class types with base classes),
+we can normally apply the `Alignment`_ and `Eliminating Bit Vector Checks
+for All-Ones Bit Vectors`_ optimizations thus simplifying the check at each
+call site to a range and alignment check.
+
+Shared library support
+======================
+
+**EXPERIMENTAL**
+
+The basic CFI mode described above assumes that the application is a
+monolithic binary; at least that all possible virtual/indirect call
+targets and the entire class hierarchy are known at link time. The
+cross-DSO mode, enabled with **-f[no-]sanitize-cfi-cross-dso** relaxes
+this requirement by allowing virtual and indirect calls to cross the
+DSO boundary.
+
+Assuming the following setup: the binary consists of several
+instrumented and several uninstrumented DSOs. Some of them may be
+dlopen-ed/dlclose-d periodically, even frequently.
+
+  - Calls made from uninstrumented DSOs are not checked and just work.
+  - Calls inside any instrumented DSO are fully protected.
+  - Calls between different instrumented DSOs are also protected, with
+     a performance penalty (in addition to the monolithic CFI
+     overhead).
+  - Calls from an instrumented DSO to an uninstrumented one are
+     unchecked and just work, with performance penalty.
+  - Calls from an instrumented DSO outside of any known DSO are
+     detected as CFI violations.
+
+In the monolithic scheme a call site is instrumented as
+
+.. code-block:: none
+
+   if (!InlinedFastCheck(f))
+     abort();
+   call *f
+
+In the cross-DSO scheme it becomes
+
+.. code-block:: none
+
+   if (!InlinedFastCheck(f))
+     __cfi_slowpath(CallSiteTypeId, f);
+   call *f
+
+CallSiteTypeId
+--------------
+
+``CallSiteTypeId`` is a stable process-wide identifier of the
+call-site type. For a virtual call site, the type in question is the class
+type; for an indirect function call it is the function signature. The
+mapping from a type to an identifier is an ABI detail. In the current,
+experimental, implementation the identifier of type T is calculated as
+follows:
+
+  -  Obtain the mangled name for "typeinfo name for T".
+  -  Calculate MD5 hash of the name as a string.
+  -  Reinterpret the first 8 bytes of the hash as a little-endian
+     64-bit integer.
+
+It is possible, but unlikely, that collisions in the
+``CallSiteTypeId`` hashing will result in weaker CFI checks that would
+still be conservatively correct.
+
+CFI_Check
+---------
+
+In the general case, only the target DSO knows whether the call to
+function ``f`` with type ``CallSiteTypeId`` is valid or not.  To
+export this information, every DSO implements
+
+.. code-block:: none
+
+   void __cfi_check(uint64 CallSiteTypeId, void *TargetAddr)
+
+This function provides external modules with access to CFI checks for the
+targets inside this DSO.  For each known ``CallSiteTypeId``, this function
+performs an ``llvm.type.test`` with the corresponding type identifier. It
+aborts if the type is unknown, or if the check fails.
+
+The basic implementation is a large switch statement over all values
+of CallSiteTypeId supported by this DSO, and each case is similar to
+the InlinedFastCheck() in the basic CFI mode.
+
+CFI Shadow
+----------
+
+To route CFI checks to the target DSO's __cfi_check function, a
+mapping from possible virtual / indirect call targets to
+the corresponding __cfi_check functions is maintained. This mapping is
+implemented as a sparse array of 2 bytes for every possible page (4096
+bytes) of memory. The table is kept readonly (FIXME: not yet) most of
+the time.
+
+There are 3 types of shadow values:
+
+  -  Address in a CFI-instrumented DSO.
+  -  Unchecked address (a “trusted” non-instrumented DSO). Encoded as
+     value 0xFFFF.
+  -  Invalid address (everything else). Encoded as value 0.
+
+For a CFI-instrumented DSO, a shadow value encodes the address of the
+__cfi_check function for all call targets in the corresponding memory
+page. If Addr is the target address, and V is the shadow value, then
+the address of __cfi_check is calculated as
+
+.. code-block:: none
+
+  __cfi_check = AlignUpTo(Addr, 4096) - (V + 1) * 4096
+
+This works as long as __cfi_check is aligned by 4096 bytes and located
+below any call targets in its DSO, but not more than 256MB apart from
+them.
+
+CFI_SlowPath
+------------
+
+The slow path check is implemented in compiler-rt library as
+
+.. code-block:: none
+
+  void __cfi_slowpath(uint64 CallSiteTypeId, void *TargetAddr)
+
+This functions loads a shadow value for ``TargetAddr``, finds the
+address of __cfi_check as described above and calls that.
+
+Position-independent executable requirement
+-------------------------------------------
+
+Cross-DSO CFI mode requires that the main executable is built as PIE.
+In non-PIE executables the address of an external function (taken from
+the main executable) is the address of that function’s PLT record in
+the main executable. This would break the CFI checks.

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/CrossCompilation.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/CrossCompilation.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/CrossCompilation.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/CrossCompilation.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,203 @@
+===================================================================
+Cross-compilation using Clang
+===================================================================
+
+Introduction
+============
+
+This document will guide you in choosing the right Clang options
+for cross-compiling your code to a different architecture. It assumes you
+already know how to compile the code in question for the host architecture,
+and that you know how to choose additional include and library paths.
+
+However, this document is *not* a "how to" and won't help you setting your
+build system or Makefiles, nor choosing the right CMake options, etc.
+Also, it does not cover all the possible options, nor does it contain
+specific examples for specific architectures. For a concrete example, the
+`instructions for cross-compiling LLVM itself
+<http://llvm.org/docs/HowToCrossCompileLLVM.html>`_ may be of interest.
+
+After reading this document, you should be familiar with the main issues
+related to cross-compilation, and what main compiler options Clang provides
+for performing cross-compilation.
+
+Cross compilation issues
+========================
+
+In GCC world, every host/target combination has its own set of binaries,
+headers, libraries, etc. So, it's usually simple to download a package
+with all files in, unzip to a directory and point the build system to
+that compiler, that will know about its location and find all it needs to
+when compiling your code.
+
+On the other hand, Clang/LLVM is natively a cross-compiler, meaning that
+one set of programs can compile to all targets by setting the ``-target``
+option. That makes it a lot easier for programmers wishing to compile to
+different platforms and architectures, and for compiler developers that
+only have to maintain one build system, and for OS distributions, that
+need only one set of main packages.
+
+But, as is true to any cross-compiler, and given the complexity of
+different architectures, OS's and options, it's not always easy finding
+the headers, libraries or binutils to generate target specific code.
+So you'll need special options to help Clang understand what target
+you're compiling to, where your tools are, etc.
+
+Another problem is that compilers come with standard libraries only (like
+``compiler-rt``, ``libcxx``, ``libgcc``, ``libm``, etc), so you'll have to
+find and make available to the build system, every other library required
+to build your software, that is specific to your target. It's not enough to
+have your host's libraries installed.
+
+Finally, not all toolchains are the same, and consequently, not every Clang
+option will work magically. Some options, like ``--sysroot`` (which
+effectively changes the logical root for headers and libraries), assume
+all your binaries and libraries are in the same directory, which may not
+true when your cross-compiler was installed by the distribution's package
+management. So, for each specific case, you may use more than one
+option, and in most cases, you'll end up setting include paths (``-I``) and
+library paths (``-L``) manually.
+
+To sum up, different toolchains can:
+ * be host/target specific or more flexible
+ * be in a single directory, or spread out across your system
+ * have different sets of libraries and headers by default
+ * need special options, which your build system won't be able to figure
+   out by itself
+
+General Cross-Compilation Options in Clang
+==========================================
+
+Target Triple
+-------------
+
+The basic option is to define the target architecture. For that, use
+``-target <triple>``. If you don't specify the target, CPU names won't
+match (since Clang assumes the host triple), and the compilation will
+go ahead, creating code for the host platform, which will break later
+on when assembling or linking.
+
+The triple has the general format ``<arch><sub>-<vendor>-<sys>-<abi>``, where:
+ * ``arch`` = ``x86``, ``arm``, ``thumb``, ``mips``, etc.
+ * ``sub`` = for ex. on ARM: ``v5``, ``v6m``, ``v7a``, ``v7m``, etc.
+ * ``vendor`` = ``pc``, ``apple``, ``nvidia``, ``ibm``, etc.
+ * ``sys`` = ``none``, ``linux``, ``win32``, ``darwin``, ``cuda``, etc.
+ * ``abi`` = ``eabi``, ``gnu``, ``android``, ``macho``, ``elf``, etc.
+
+The sub-architecture options are available for their own architectures,
+of course, so "x86v7a" doesn't make sense. The vendor needs to be 
+specified only if there's a relevant change, for instance between PC
+and Apple. Most of the time it can be omitted (and Unknown)
+will be assumed, which sets the defaults for the specified architecture.
+The system name is generally the OS (linux, darwin), but could be special
+like the bare-metal "none".
+
+When a parameter is not important, it can be omitted, or you can
+choose ``unknown`` and the defaults will be used. If you choose a parameter
+that Clang doesn't know, like ``blerg``, it'll ignore and assume
+``unknown``, which is not always desired, so be careful.
+
+Finally, the ABI option is something that will pick default CPU/FPU,
+define the specific behaviour of your code (PCS, extensions),
+and also choose the correct library calls, etc.
+
+CPU, FPU, ABI
+-------------
+
+Once your target is specified, it's time to pick the hardware you'll
+be compiling to. For every architecture, a default set of CPU/FPU/ABI
+will be chosen, so you'll almost always have to change it via flags.
+
+Typical flags include:
+ * ``-mcpu=<cpu-name>``, like x86-64, swift, cortex-a15
+ * ``-mfpu=<fpu-name>``, like SSE3, NEON, controlling the FP unit available
+ * ``-mfloat-abi=<fabi>``, like soft, hard, controlling which registers
+   to use for floating-point
+
+The default is normally the common denominator, so that Clang doesn't
+generate code that breaks. But that also means you won't get the best
+code for your specific hardware, which may mean orders of magnitude
+slower than you expect.
+
+For example, if your target is ``arm-none-eabi``, the default CPU will
+be ``arm7tdmi`` using soft float, which is extremely slow on modern cores,
+whereas if your triple is ``armv7a-none-eabi``, it'll be Cortex-A8 with
+NEON, but still using soft-float, which is much better, but still not
+great.
+
+Toolchain Options
+-----------------
+
+There are three main options to control access to your cross-compiler:
+``--sysroot``, ``-I``, and ``-L``. The two last ones are well known,
+but they're particularly important for additional libraries
+and headers that are specific to your target.
+
+There are two main ways to have a cross-compiler:
+
+#. When you have extracted your cross-compiler from a zip file into
+   a directory, you have to use ``--sysroot=<path>``. The path is the
+   root directory where you have unpacked your file, and Clang will
+   look for the directories ``bin``, ``lib``, ``include`` in there.
+
+   In this case, your setup should be pretty much done (if no
+   additional headers or libraries are needed), as Clang will find
+   all binaries it needs (assembler, linker, etc) in there.
+
+#. When you have installed via a package manager (modern Linux
+   distributions have cross-compiler packages available), make
+   sure the target triple you set is *also* the prefix of your
+   cross-compiler toolchain.
+
+   In this case, Clang will find the other binaries (assembler,
+   linker), but not always where the target headers and libraries
+   are. People add system-specific clues to Clang often, but as
+   things change, it's more likely that it won't find than the
+   other way around.
+
+   So, here, you'll be a lot safer if you specify the include/library
+   directories manually (via ``-I`` and ``-L``).
+
+Target-Specific Libraries
+=========================
+
+All libraries that you compile as part of your build will be
+cross-compiled to your target, and your build system will probably
+find them in the right place. But all dependencies that are
+normally checked against (like ``libxml`` or ``libz`` etc) will match
+against the host platform, not the target.
+
+So, if the build system is not aware that you want to cross-compile
+your code, it will get every dependency wrong, and your compilation
+will fail during build time, not configure time.
+
+Also, finding the libraries for your target are not as easy
+as for your host machine. There aren't many cross-libraries available
+as packages to most OS's, so you'll have to either cross-compile them
+from source, or download the package for your target platform,
+extract the libraries and headers, put them in specific directories
+and add ``-I`` and ``-L`` pointing to them.
+
+Also, some libraries have different dependencies on different targets,
+so configuration tools to find dependencies in the host can get the
+list wrong for the target platform. This means that the configuration
+of your build can get things wrong when setting their own library
+paths, and you'll have to augment it via additional flags (configure,
+Make, CMake, etc).
+
+Multilibs
+---------
+
+When you want to cross-compile to more than one configuration, for
+example hard-float-ARM and soft-float-ARM, you'll have to have multiple
+copies of your libraries and (possibly) headers.
+
+Some Linux distributions have support for Multilib, which handle that
+for you in an easier way, but if you're not careful and, for instance,
+forget to specify ``-ccc-gcc-name armv7l-linux-gnueabihf-gcc`` (which
+uses hard-float), Clang will pick the ``armv7l-linux-gnueabi-ld``
+(which uses soft-float) and linker errors will happen.
+
+The same is true if you're compiling for different ABIs, like ``gnueabi``
+and ``androideabi``, and might even link and run, but produce run-time
+errors, which are much harder to track down and fix.

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/DataFlowSanitizer.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/DataFlowSanitizer.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/DataFlowSanitizer.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/DataFlowSanitizer.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,158 @@
+=================
+DataFlowSanitizer
+=================
+
+.. toctree::
+   :hidden:
+
+   DataFlowSanitizerDesign
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+DataFlowSanitizer is a generalised dynamic data flow analysis.
+
+Unlike other Sanitizer tools, this tool is not designed to detect a
+specific class of bugs on its own.  Instead, it provides a generic
+dynamic data flow analysis framework to be used by clients to help
+detect application-specific issues within their own code.
+
+Usage
+=====
+
+With no program changes, applying DataFlowSanitizer to a program
+will not alter its behavior.  To use DataFlowSanitizer, the program
+uses API functions to apply tags to data to cause it to be tracked, and to
+check the tag of a specific data item.  DataFlowSanitizer manages
+the propagation of tags through the program according to its data flow.
+
+The APIs are defined in the header file ``sanitizer/dfsan_interface.h``.
+For further information about each function, please refer to the header
+file.
+
+ABI List
+--------
+
+DataFlowSanitizer uses a list of functions known as an ABI list to decide
+whether a call to a specific function should use the operating system's native
+ABI or whether it should use a variant of this ABI that also propagates labels
+through function parameters and return values.  The ABI list file also controls
+how labels are propagated in the former case.  DataFlowSanitizer comes with a
+default ABI list which is intended to eventually cover the glibc library on
+Linux but it may become necessary for users to extend the ABI list in cases
+where a particular library or function cannot be instrumented (e.g. because
+it is implemented in assembly or another language which DataFlowSanitizer does
+not support) or a function is called from a library or function which cannot
+be instrumented.
+
+DataFlowSanitizer's ABI list file is a :doc:`SanitizerSpecialCaseList`.
+The pass treats every function in the ``uninstrumented`` category in the
+ABI list file as conforming to the native ABI.  Unless the ABI list contains
+additional categories for those functions, a call to one of those functions
+will produce a warning message, as the labelling behavior of the function
+is unknown.  The other supported categories are ``discard``, ``functional``
+and ``custom``.
+
+* ``discard`` -- To the extent that this function writes to (user-accessible)
+  memory, it also updates labels in shadow memory (this condition is trivially
+  satisfied for functions which do not write to user-accessible memory).  Its
+  return value is unlabelled.
+* ``functional`` -- Like ``discard``, except that the label of its return value
+  is the union of the label of its arguments.
+* ``custom`` -- Instead of calling the function, a custom wrapper ``__dfsw_F``
+  is called, where ``F`` is the name of the function.  This function may wrap
+  the original function or provide its own implementation.  This category is
+  generally used for uninstrumentable functions which write to user-accessible
+  memory or which have more complex label propagation behavior.  The signature
+  of ``__dfsw_F`` is based on that of ``F`` with each argument having a
+  label of type ``dfsan_label`` appended to the argument list.  If ``F``
+  is of non-void return type a final argument of type ``dfsan_label *``
+  is appended to which the custom function can store the label for the
+  return value.  For example:
+
+.. code-block:: c++
+
+  void f(int x);
+  void __dfsw_f(int x, dfsan_label x_label);
+
+  void *memcpy(void *dest, const void *src, size_t n);
+  void *__dfsw_memcpy(void *dest, const void *src, size_t n,
+                      dfsan_label dest_label, dfsan_label src_label,
+                      dfsan_label n_label, dfsan_label *ret_label);
+
+If a function defined in the translation unit being compiled belongs to the
+``uninstrumented`` category, it will be compiled so as to conform to the
+native ABI.  Its arguments will be assumed to be unlabelled, but it will
+propagate labels in shadow memory.
+
+For example:
+
+.. code-block:: none
+
+  # main is called by the C runtime using the native ABI.
+  fun:main=uninstrumented
+  fun:main=discard
+
+  # malloc only writes to its internal data structures, not user-accessible memory.
+  fun:malloc=uninstrumented
+  fun:malloc=discard
+
+  # tolower is a pure function.
+  fun:tolower=uninstrumented
+  fun:tolower=functional
+
+  # memcpy needs to copy the shadow from the source to the destination region.
+  # This is done in a custom function.
+  fun:memcpy=uninstrumented
+  fun:memcpy=custom
+
+Example
+=======
+
+The following program demonstrates label propagation by checking that
+the correct labels are propagated.
+
+.. code-block:: c++
+
+  #include <sanitizer/dfsan_interface.h>
+  #include <assert.h>
+
+  int main(void) {
+    int i = 1;
+    dfsan_label i_label = dfsan_create_label("i", 0);
+    dfsan_set_label(i_label, &i, sizeof(i));
+
+    int j = 2;
+    dfsan_label j_label = dfsan_create_label("j", 0);
+    dfsan_set_label(j_label, &j, sizeof(j));
+
+    int k = 3;
+    dfsan_label k_label = dfsan_create_label("k", 0);
+    dfsan_set_label(k_label, &k, sizeof(k));
+
+    dfsan_label ij_label = dfsan_get_label(i + j);
+    assert(dfsan_has_label(ij_label, i_label));
+    assert(dfsan_has_label(ij_label, j_label));
+    assert(!dfsan_has_label(ij_label, k_label));
+
+    dfsan_label ijk_label = dfsan_get_label(i + j + k);
+    assert(dfsan_has_label(ijk_label, i_label));
+    assert(dfsan_has_label(ijk_label, j_label));
+    assert(dfsan_has_label(ijk_label, k_label));
+
+    return 0;
+  }
+
+Current status
+==============
+
+DataFlowSanitizer is a work in progress, currently under development for
+x86\_64 Linux.
+
+Design
+======
+
+Please refer to the :doc:`design document<DataFlowSanitizerDesign>`.

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,220 @@
+DataFlowSanitizer Design Document
+=================================
+
+This document sets out the design for DataFlowSanitizer, a general
+dynamic data flow analysis.  Unlike other Sanitizer tools, this tool is
+not designed to detect a specific class of bugs on its own. Instead,
+it provides a generic dynamic data flow analysis framework to be used
+by clients to help detect application-specific issues within their
+own code.
+
+DataFlowSanitizer is a program instrumentation which can associate
+a number of taint labels with any data stored in any memory region
+accessible by the program. The analysis is dynamic, which means that
+it operates on a running program, and tracks how the labels propagate
+through that program. The tool shall support a large (>100) number
+of labels, such that programs which operate on large numbers of data
+items may be analysed with each data item being tracked separately.
+
+Use Cases
+---------
+
+This instrumentation can be used as a tool to help monitor how data
+flows from a program's inputs (sources) to its outputs (sinks).
+This has applications from a privacy/security perspective in that
+one can audit how a sensitive data item is used within a program and
+ensure it isn't exiting the program anywhere it shouldn't be.
+
+Interface
+---------
+
+A number of functions are provided which will create taint labels,
+attach labels to memory regions and extract the set of labels
+associated with a specific memory region. These functions are declared
+in the header file ``sanitizer/dfsan_interface.h``.
+
+.. code-block:: c
+
+  /// Creates and returns a base label with the given description and user data.
+  dfsan_label dfsan_create_label(const char *desc, void *userdata);
+
+  /// Sets the label for each address in [addr,addr+size) to \c label.
+  void dfsan_set_label(dfsan_label label, void *addr, size_t size);
+
+  /// Sets the label for each address in [addr,addr+size) to the union of the
+  /// current label for that address and \c label.
+  void dfsan_add_label(dfsan_label label, void *addr, size_t size);
+
+  /// Retrieves the label associated with the given data.
+  ///
+  /// The type of 'data' is arbitrary.  The function accepts a value of any type,
+  /// which can be truncated or extended (implicitly or explicitly) as necessary.
+  /// The truncation/extension operations will preserve the label of the original
+  /// value.
+  dfsan_label dfsan_get_label(long data);
+
+  /// Retrieves a pointer to the dfsan_label_info struct for the given label.
+  const struct dfsan_label_info *dfsan_get_label_info(dfsan_label label);
+
+  /// Returns whether the given label label contains the label elem.
+  int dfsan_has_label(dfsan_label label, dfsan_label elem);
+
+  /// If the given label label contains a label with the description desc, returns
+  /// that label, else returns 0.
+  dfsan_label dfsan_has_label_with_desc(dfsan_label label, const char *desc);
+
+Taint label representation
+--------------------------
+
+As stated above, the tool must track a large number of taint
+labels. This poses an implementation challenge, as most multiple-label
+tainting systems assign one label per bit to shadow storage, and
+union taint labels using a bitwise or operation. This will not scale
+to clients which use hundreds or thousands of taint labels, as the
+label union operation becomes O(n) in the number of supported labels,
+and data associated with it will quickly dominate the live variable
+set, causing register spills and hampering performance.
+
+Instead, a low overhead approach is proposed which is best-case O(log\
+:sub:`2` n) during execution. The underlying assumption is that
+the required space of label unions is sparse, which is a reasonable
+assumption to make given that we are optimizing for the case where
+applications mostly copy data from one place to another, without often
+invoking the need for an actual union operation. The representation
+of a taint label is a 16-bit integer, and new labels are allocated
+sequentially from a pool. The label identifier 0 is special, and means
+that the data item is unlabelled.
+
+When a label union operation is requested at a join point (any
+arithmetic or logical operation with two or more operands, such as
+addition), the code checks whether a union is required, whether the
+same union has been requested before, and whether one union label
+subsumes the other. If so, it returns the previously allocated union
+label. If not, it allocates a new union label from the same pool used
+for new labels.
+
+Specifically, the instrumentation pass will insert code like this
+to decide the union label ``lu`` for a pair of labels ``l1``
+and ``l2``:
+
+.. code-block:: c
+
+  if (l1 == l2)
+    lu = l1;
+  else
+    lu = __dfsan_union(l1, l2);
+
+The equality comparison is outlined, to provide an early exit in
+the common cases where the program is processing unlabelled data, or
+where the two data items have the same label.  ``__dfsan_union`` is
+a runtime library function which performs all other union computation.
+
+Further optimizations are possible, for example if ``l1`` is known
+at compile time to be zero (e.g. it is derived from a constant),
+``l2`` can be used for ``lu``, and vice versa.
+
+Memory layout and label management
+----------------------------------
+
+The following is the current memory layout for Linux/x86\_64:
+
++---------------+---------------+--------------------+
+|    Start      |    End        |        Use         |
++===============+===============+====================+
+| 0x700000008000|0x800000000000 | application memory |
++---------------+---------------+--------------------+
+| 0x200200000000|0x700000008000 |       unused       |
++---------------+---------------+--------------------+
+| 0x200000000000|0x200200000000 |    union table     |
++---------------+---------------+--------------------+
+| 0x000000010000|0x200000000000 |   shadow memory    |
++---------------+---------------+--------------------+
+| 0x000000000000|0x000000010000 | reserved by kernel |
++---------------+---------------+--------------------+
+
+Each byte of application memory corresponds to two bytes of shadow
+memory, which are used to store its taint label. As for LLVM SSA
+registers, we have not found it necessary to associate a label with
+each byte or bit of data, as some other tools do. Instead, labels are
+associated directly with registers.  Loads will result in a union of
+all shadow labels corresponding to bytes loaded (which most of the
+time will be short circuited by the initial comparison) and stores will
+result in a copy of the label to the shadow of all bytes stored to.
+
+Propagating labels through arguments
+------------------------------------
+
+In order to propagate labels through function arguments and return values,
+DataFlowSanitizer changes the ABI of each function in the translation unit.
+There are currently two supported ABIs:
+
+* Args -- Argument and return value labels are passed through additional
+  arguments and by modifying the return type.
+
+* TLS -- Argument and return value labels are passed through TLS variables
+  ``__dfsan_arg_tls`` and ``__dfsan_retval_tls``.
+
+The main advantage of the TLS ABI is that it is more tolerant of ABI mismatches
+(TLS storage is not shared with any other form of storage, whereas extra
+arguments may be stored in registers which under the native ABI are not used
+for parameter passing and thus could contain arbitrary values).  On the other
+hand the args ABI is more efficient and allows ABI mismatches to be more easily
+identified by checking for nonzero labels in nominally unlabelled programs.
+
+Implementing the ABI list
+-------------------------
+
+The `ABI list <DataFlowSanitizer.html#abi-list>`_ provides a list of functions
+which conform to the native ABI, each of which is callable from an instrumented
+program.  This is implemented by replacing each reference to a native ABI
+function with a reference to a function which uses the instrumented ABI.
+Such functions are automatically-generated wrappers for the native functions.
+For example, given the ABI list example provided in the user manual, the
+following wrappers will be generated under the args ABI:
+
+.. code-block:: llvm
+
+    define linkonce_odr { i8*, i16 } @"dfsw$malloc"(i64 %0, i16 %1) {
+    entry:
+      %2 = call i8* @malloc(i64 %0)
+      %3 = insertvalue { i8*, i16 } undef, i8* %2, 0
+      %4 = insertvalue { i8*, i16 } %3, i16 0, 1
+      ret { i8*, i16 } %4
+    }
+
+    define linkonce_odr { i32, i16 } @"dfsw$tolower"(i32 %0, i16 %1) {
+    entry:
+      %2 = call i32 @tolower(i32 %0)
+      %3 = insertvalue { i32, i16 } undef, i32 %2, 0
+      %4 = insertvalue { i32, i16 } %3, i16 %1, 1
+      ret { i32, i16 } %4
+    }
+
+    define linkonce_odr { i8*, i16 } @"dfsw$memcpy"(i8* %0, i8* %1, i64 %2, i16 %3, i16 %4, i16 %5) {
+    entry:
+      %labelreturn = alloca i16
+      %6 = call i8* @__dfsw_memcpy(i8* %0, i8* %1, i64 %2, i16 %3, i16 %4, i16 %5, i16* %labelreturn)
+      %7 = load i16* %labelreturn
+      %8 = insertvalue { i8*, i16 } undef, i8* %6, 0
+      %9 = insertvalue { i8*, i16 } %8, i16 %7, 1
+      ret { i8*, i16 } %9
+    }
+
+As an optimization, direct calls to native ABI functions will call the
+native ABI function directly and the pass will compute the appropriate label
+internally.  This has the advantage of reducing the number of union operations
+required when the return value label is known to be zero (i.e. ``discard``
+functions, or ``functional`` functions with known unlabelled arguments).
+
+Checking ABI Consistency
+------------------------
+
+DFSan changes the ABI of each function in the module.  This makes it possible
+for a function with the native ABI to be called with the instrumented ABI,
+or vice versa, thus possibly invoking undefined behavior.  A simple way
+of statically detecting instances of this problem is to prepend the prefix
+"dfs$" to the name of each instrumented-ABI function.
+
+This will not catch every such problem; in particular function pointers passed
+across the instrumented-native barrier cannot be used on the other side.
+These problems could potentially be caught dynamically.

Added: www-releases/trunk/3.9.0/tools/clang/docs/_sources/DriverInternals.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.9.0/tools/clang/docs/_sources/DriverInternals.txt?rev=280493&view=auto
==============================================================================
--- www-releases/trunk/3.9.0/tools/clang/docs/_sources/DriverInternals.txt (added)
+++ www-releases/trunk/3.9.0/tools/clang/docs/_sources/DriverInternals.txt Fri Sep  2 10:56:46 2016
@@ -0,0 +1,400 @@
+=========================
+Driver Design & Internals
+=========================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document describes the Clang driver. The purpose of this document
+is to describe both the motivation and design goals for the driver, as
+well as details of the internal implementation.
+
+Features and Goals
+==================
+
+The Clang driver is intended to be a production quality compiler driver
+providing access to the Clang compiler and tools, with a command line
+interface which is compatible with the gcc driver.
+
+Although the driver is part of and driven by the Clang project, it is
+logically a separate tool which shares many of the same goals as Clang:
+
+.. contents:: Features
+   :local:
+
+GCC Compatibility
+-----------------
+
+The number one goal of the driver is to ease the adoption of Clang by
+allowing users to drop Clang into a build system which was designed to
+call GCC. Although this makes the driver much more complicated than
+might otherwise be necessary, we decided that being very compatible with
+the gcc command line interface was worth it in order to allow users to
+quickly test clang on their projects.
+
+Flexible
+--------
+
+The driver was designed to be flexible and easily accommodate new uses
+as we grow the clang and LLVM infrastructure. As one example, the driver
+can easily support the introduction of tools which have an integrated
+assembler; something we hope to add to LLVM in the future.
+
+Similarly, most of the driver functionality is kept in a library which
+can be used to build other tools which want to implement or accept a gcc
+like interface.
+
+Low Overhead
+------------
+
+The driver should have as little overhead as possible. In practice, we
+found that the gcc driver by itself incurred a small but meaningful
+overhead when compiling many small files. The driver doesn't do much
+work compared to a compilation, but we have tried to keep it as
+efficient as possible by following a few simple principles:
+
+-  Avoid memory allocation and string copying when possible.
+-  Don't parse arguments more than once.
+-  Provide a few simple interfaces for efficiently searching arguments.
+
+Simple
+------
+
+Finally, the driver was designed to be "as simple as possible", given
+the other goals. Notably, trying to be completely compatible with the
+gcc driver adds a significant amount of complexity. However, the design
+of the driver attempts to mitigate this complexity by dividing the
+process into a number of independent stages instead of a single
+monolithic task.
+
+Internal Design and Implementation
+==================================
+
+.. contents::
+   :local:
+   :depth: 1
+
+Internals Introduction
+----------------------
+
+In order to satisfy the stated goals, the driver was designed to
+completely subsume the functionality of the gcc executable; that is, the
+driver should not need to delegate to gcc to perform subtasks. On
+Darwin, this implies that the Clang driver also subsumes the gcc
+driver-driver, which is used to implement support for building universal
+images (binaries and object files). This also implies that the driver
+should be able to call the language specific compilers (e.g. cc1)
+directly, which means that it must have enough information to forward
+command line arguments to child processes correctly.
+
+Design Overview
+---------------
+
+The diagram below shows the significant components of the driver
+architecture and how they relate to one another. The orange components
+represent concrete data structures built by the driver, the green
+components indicate conceptually distinct stages which manipulate these
+data structures, and the blue components are important helper classes.
+
+.. image:: DriverArchitecture.png
+   :align: center
+   :alt: Driver Architecture Diagram
+
+Driver Stages
+-------------
+
+The driver functionality is conceptually divided into five stages:
+
+#. **Parse: Option Parsing**
+
+   The command line argument strings are decomposed into arguments
+   (``Arg`` instances). The driver expects to understand all available
+   options, although there is some facil