[www-releases] r342530 - 7.0.0 files

Hans Wennborg via llvm-commits llvm-commits at lists.llvm.org
Wed Sep 19 02:40:15 PDT 2018


Added: www-releases/trunk/7.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/AttributeReference.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,3899 @@
+..
+  -------------------------------------------------------------------
+  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
+===================
+
+
+#pragma omp declare simd
+------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","", "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:: none
+
+    #pragma omp declare simd [clause[[,] clause] ...] new-line
+    [#pragma omp declare simd [clause[[,] clause] ...] new-line]
+    [...]
+    function definition or declaration
+
+where clause is one of the following:
+
+  .. code-block:: none
+
+    simdlen(length)
+    linear(argument-list[:constant-linear-step])
+    aligned(argument-list[:alignment])
+    uniform(argument-list)
+    inbranch
+    notinbranch
+
+
+#pragma omp declare target
+--------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","", "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
+
+
+_Noreturn
+---------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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.
+
+
+abi_tag (gnu::abi_tag)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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. Therefore, the old code could keep using
+the old manged name and the new code will use the new mangled name with tags.
+
+
+acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", ""
+
+Marks a function as acquiring a capability.
+
+
+alloc_align (gnu::alloc_align)
+------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", ""
+
+Use ``__attribute__((alloc_align(<alignment>))`` on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) is at least as aligned as the value of the indicated parameter. The
+parameter is given by its index in the list of formal parameters; the first
+parameter has index 1 unless the function is a C++ non-static member function,
+in which case the first parameter has index 2 to account for the implicit ``this``
+parameter.
+
+.. code-block:: c++
+
+  // The returned pointer has the alignment specified by the first parameter.
+  void *a(size_t align) __attribute__((alloc_align(1)));
+
+  // The returned pointer has the alignment specified by the second parameter.
+  void *b(void *v, size_t align) __attribute__((alloc_align(2)));
+
+  // The returned pointer has the alignment specified by the second visible
+  // parameter, however it must be adjusted for the implicit 'this' parameter.
+  void *Foo::b(void *v, size_t align) __attribute__((alloc_align(3)));
+
+Note that this attribute merely informs the compiler that a function always
+returns a sufficiently aligned pointer. It does not cause the compiler to
+emit code to enforce that alignment.  The behavior is undefined if the returned
+poitner is not sufficiently aligned.
+
+
+alloc_size (gnu::alloc_size)
+----------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+The ``alloc_size`` attribute can be placed on functions that return pointers in
+order to hint to the compiler how many bytes of memory will be available at the
+returned pointer. ``alloc_size`` takes one or two arguments.
+
+- ``alloc_size(N)`` implies that argument number N equals the number of
+  available bytes at the returned pointer.
+- ``alloc_size(N, M)`` implies that the product of argument number N and
+  argument number M equals the number of available bytes at the returned
+  pointer.
+
+Argument numbers are 1-based.
+
+An example of how to use ``alloc_size``
+
+.. code-block:: c
+
+  void *my_malloc(int a) __attribute__((alloc_size(1)));
+  void *my_calloc(int a, int b) __attribute__((alloc_size(1, 2)));
+
+  int main() {
+    void *const p = my_malloc(100);
+    assert(__builtin_object_size(p, 0) == 100);
+    void *const a = my_calloc(20, 5);
+    assert(__builtin_object_size(a, 0) == 100);
+  }
+
+.. Note:: This attribute works differently in clang than it does in GCC.
+  Specifically, clang will only trace ``const`` pointers (as above); we give up
+  on pointers that are not marked as ``const``. In the vast majority of cases,
+  this is unimportant, because LLVM has support for the ``alloc_size``
+  attribute. However, this may cause mildly unintuitive behavior when used with
+  other attributes, such as ``enable_if``.
+
+
+artificial (gnu::artificial)
+----------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", ""
+
+The ``artificial`` attribute can be applied to an inline function. If such a
+function is inlined, the attribute indicates that debuggers should associate
+the resulting instructions with the call site, rather than with the
+corresponding line within the inlined callee.
+
+
+assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)
+-------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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 (clang::availability, clang::availability)
+-------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "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 macOS 10.4,
+deprecated in macOS 10.6, and obsoleted in macOS 10.7.  This information
+is used by Clang to determine when it is safe to use ``f``: for example, if
+Clang is instructed to compile code for macOS 10.5, a call to ``f()``
+succeeds.  If Clang is instructed to compile code for macOS 10.6, the call
+succeeds but Clang emits a warning specifying that the function is deprecated.
+Finally, if Clang is instructed to compile code for macOS 10.7, the call
+fails because ``f()`` is no longer available.
+
+The availability attribute is a comma-separated list starting with the
+platform name and then including clauses specifying important milestones in the
+declaration's lifetime (in any order) along with additional information.  Those
+clauses can be:
+
+introduced=\ *version*
+  The first version in which this declaration was introduced.
+
+deprecated=\ *version*
+  The first version in which this declaration was deprecated, meaning that
+  users should migrate away from this API.
+
+obsoleted=\ *version*
+  The first version in which this declaration was obsoleted, meaning that it
+  was removed completely and can no longer be used.
+
+unavailable
+  This declaration is never available on this platform.
+
+message=\ *string-literal*
+  Additional message text that Clang will provide when emitting a warning or
+  error about use of a deprecated or obsoleted declaration.  Useful to direct
+  users to replacement APIs.
+
+replacement=\ *string-literal*
+  Additional message text that Clang will use to provide Fix-It when emitting
+  a warning about use of a deprecated declaration. The Fix-It will replace
+  the deprecated declaration with the new declaration specified.
+
+Multiple availability attributes can be placed on a declaration, which may
+correspond to different platforms.  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 macOS operating system.  The minimum deployment target is
+  specified by the ``-mmacosx-version-min=*version*`` command-line argument.
+  ``macosx`` is supported for backward-compatibility reasons, but it is
+  deprecated.
+
+``tvos``
+  Apple's tvOS operating system.  The minimum deployment target is specified by
+  the ``-mtvos-version-min=*version*`` command-line argument.
+
+``watchos``
+  Apple's watchOS operating system.  The minimum deployment target is specified by
+  the ``-mwatchos-version-min=*version*`` command-line argument.
+
+A declaration can typically be used even when deploying back to a platform
+version prior to when the declaration was introduced.  When this happens, the
+declaration is `weakly linked
+<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_,
+as if the ``weak_import`` attribute were added to the declaration.  A
+weakly-linked declaration may or may not be present a run-time, and a program
+can determine whether the declaration is present by checking whether the
+address of that declaration is non-NULL.
+
+The flag ``strict`` disallows using API when deploying back to a
+platform version prior to when the declaration was introduced.  An
+attempt to use such API before its introduction causes a hard error.
+Weakly-linking is almost always a better API choice, since it allows
+users to query availability at runtime.
+
+If there are multiple declarations of the same entity, the availability
+attributes must either match on a per-platform basis or later
+declarations must not have availability attributes for that
+platform. For example:
+
+.. code-block:: c
+
+  void g(void) __attribute__((availability(macos,introduced=10.4)));
+  void g(void) __attribute__((availability(macos,introduced=10.4))); // okay, matches
+  void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
+  void g(void); // okay, inherits both macos and ios availability from above.
+  void g(void) __attribute__((availability(macos,introduced=10.5))); // error: mismatch
+
+When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
+
+.. code-block:: objc
+
+  @interface A
+  - (id)method __attribute__((availability(macos,introduced=10.4)));
+  - (id)method2 __attribute__((availability(macos,introduced=10.4)));
+  @end
+
+  @interface B : A
+  - (id)method __attribute__((availability(macos,introduced=10.3))); // okay: method moved into base class later
+  - (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4
+  @end
+
+Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from
+``<os/availability.h>`` can simplify the spelling:
+
+.. code-block:: objc
+
+  @interface A
+  - (id)method API_AVAILABLE(macos(10.11)));
+  - (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0));
+  @end
+
+Also see the documentation for `@available
+<http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-available>`_
+
+
+carries_dependency
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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.
+
+
+code_seg
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","X","", "", ""
+
+The ``__declspec(code_seg)`` attribute enables the placement of code into separate
+named segments that can be paged or locked in memory individually. This attribute
+is used to control the placement of instantiated templates and compiler-generated
+code. See the documentation for `__declspec(code_seg)`_ on MSDN.
+
+.. _`__declspec(code_seg)`: http://msdn.microsoft.com/en-us/library/dn636922.aspx
+
+
+convergent (clang::convergent, clang::convergent)
+-------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+The ``convergent`` attribute can be placed on a function declaration. It is
+translated into the LLVM ``convergent`` attribute, which indicates that the call
+instructions of a function with this attribute cannot be made control-dependent
+on any additional values.
+
+In languages designed for SPMD/SIMT programming model, e.g. OpenCL or CUDA,
+the call instructions of a function with this attribute must be executed by
+all work items or threads in a work group or sub group.
+
+This attribute is different from ``noduplicate`` because it allows duplicating
+function calls if it can be proved that the duplicated function calls are
+not made control-dependent on any additional values, e.g., unrolling a loop
+executed by all work items.
+
+Sample usage:
+.. code-block:: c
+
+  void convfunc(void) __attribute__((convergent));
+  // Setting it as a C++11 attribute is also valid in a C++ program.
+  // void convfunc(void) [[clang::convergent]];
+
+
+cpu_dispatch (clang::cpu_dispatch, clang::cpu_dispatch)
+-------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and
+resolve multiversioned functions. This form of multiversioning provides a
+mechanism for declaring versions across translation units and manually
+specifying the resolved function list. A specified CPU defines a set of minimum
+features that are required for the function to be called. The result of this is
+that future processors execute the most restrictive version of the function the
+new processor can execute.
+
+Function versions are defined with ``cpu_specific``, which takes one or more CPU
+names as a parameter. For example:
+
+.. code-block:: c
+
+  // Declares and defines the ivybridge version of single_cpu.
+  __attribute__((cpu_specific(ivybridge)))
+  void single_cpu(void){}
+
+  // Declares and defines the atom version of single_cpu.
+  __attribute__((cpu_specific(atom)))
+  void single_cpu(void){}
+
+  // Declares and defines both the ivybridge and atom version of multi_cpu.
+  __attribute__((cpu_specific(ivybridge, atom)))
+  void multi_cpu(void){}
+
+A dispatching (or resolving) function can be declared anywhere in a project's
+source code with ``cpu_dispatch``. This attribute takes one or more CPU names
+as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch``
+are not expected to be defined, only declared. If such a marked function has a
+definition, any side effects of the function are ignored; trivial function
+bodies are permissible for ICC compatibility.
+
+.. code-block:: c
+
+  // Creates a resolver for single_cpu above.
+  __attribute__((cpu_dispatch(ivybridge, atom)))
+  void single_cpu(void){}
+
+  // Creates a resolver for multi_cpu, but adds a 3rd version defined in another
+  // translation unit.
+  __attribute__((cpu_dispatch(ivybridge, atom, sandybridge)))
+  void multi_cpu(void){}
+
+Note that it is possible to have a resolving function that dispatches based on
+more or fewer options than are present in the program. Specifying fewer will
+result in the omitted options not being considered during resolution. Specifying
+a version for resolution that isn't defined in the program will result in a
+linking failure.
+
+It is also possible to specify a CPU name of ``generic`` which will be resolved
+if the executing processor doesn't satisfy the features required in the CPU
+name. The behavior of a program executing on a processor that doesn't satisfy
+any option of a multiversioned function is undefined.
+
+
+cpu_specific (clang::cpu_specific, clang::cpu_specific)
+-------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+The ``cpu_specific`` and ``cpu_dispatch`` attributes are used to define and
+resolve multiversioned functions. This form of multiversioning provides a
+mechanism for declaring versions across translation units and manually
+specifying the resolved function list. A specified CPU defines a set of minimum
+features that are required for the function to be called. The result of this is
+that future processors execute the most restrictive version of the function the
+new processor can execute.
+
+Function versions are defined with ``cpu_specific``, which takes one or more CPU
+names as a parameter. For example:
+
+.. code-block:: c
+
+  // Declares and defines the ivybridge version of single_cpu.
+  __attribute__((cpu_specific(ivybridge)))
+  void single_cpu(void){}
+
+  // Declares and defines the atom version of single_cpu.
+  __attribute__((cpu_specific(atom)))
+  void single_cpu(void){}
+
+  // Declares and defines both the ivybridge and atom version of multi_cpu.
+  __attribute__((cpu_specific(ivybridge, atom)))
+  void multi_cpu(void){}
+
+A dispatching (or resolving) function can be declared anywhere in a project's
+source code with ``cpu_dispatch``. This attribute takes one or more CPU names
+as a parameter (like ``cpu_specific``). Functions marked with ``cpu_dispatch``
+are not expected to be defined, only declared. If such a marked function has a
+definition, any side effects of the function are ignored; trivial function
+bodies are permissible for ICC compatibility.
+
+.. code-block:: c
+
+  // Creates a resolver for single_cpu above.
+  __attribute__((cpu_dispatch(ivybridge, atom)))
+  void single_cpu(void){}
+
+  // Creates a resolver for multi_cpu, but adds a 3rd version defined in another
+  // translation unit.
+  __attribute__((cpu_dispatch(ivybridge, atom, sandybridge)))
+  void multi_cpu(void){}
+
+Note that it is possible to have a resolving function that dispatches based on
+more or fewer options than are present in the program. Specifying fewer will
+result in the omitted options not being considered during resolution. Specifying
+a version for resolution that isn't defined in the program will result in a
+linking failure.
+
+It is also possible to specify a CPU name of ``generic`` which will be resolved
+if the executing processor doesn't satisfy the features required in the CPU
+name. The behavior of a program executing on a processor that doesn't satisfy
+any option of a multiversioned function is undefined.
+
+
+deprecated (gnu::deprecated)
+----------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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.
+
+
+diagnose_if
+-----------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","","","","", "", ""
+
+The ``diagnose_if`` attribute can be placed on function declarations to emit
+warnings or errors at compile-time if calls to the attributed function meet
+certain user-defined criteria. For example:
+
+.. code-block:: c
+
+  void abs(int a)
+    __attribute__((diagnose_if(a >= 0, "Redundant abs call", "warning")));
+  void must_abs(int a)
+    __attribute__((diagnose_if(a >= 0, "Redundant abs call", "error")));
+
+  int val = abs(1); // warning: Redundant abs call
+  int val2 = must_abs(1); // error: Redundant abs call
+  int val3 = abs(val);
+  int val4 = must_abs(val); // Because run-time checks are not emitted for
+                            // diagnose_if attributes, this executes without
+                            // issue.
+
+
+``diagnose_if`` is closely related to ``enable_if``, with a few key differences:
+
+* Overload resolution is not aware of ``diagnose_if`` attributes: they're
+  considered only after we select the best candidate from a given candidate set.
+* Function declarations that differ only in their ``diagnose_if`` attributes are
+  considered to be redeclarations of the same function (not overloads).
+* If the condition provided to ``diagnose_if`` cannot be evaluated, no
+  diagnostic will be emitted.
+
+Otherwise, ``diagnose_if`` is essentially the logical negation of ``enable_if``.
+
+As a result of bullet number two, ``diagnose_if`` attributes will stack on the
+same function. For example:
+
+.. code-block:: c
+
+  int foo() __attribute__((diagnose_if(1, "diag1", "warning")));
+  int foo() __attribute__((diagnose_if(1, "diag2", "warning")));
+
+  int bar = foo(); // warning: diag1
+                   // warning: diag2
+  int (*fooptr)(void) = foo; // warning: diag1
+                             // warning: diag2
+
+  constexpr int supportsAPILevel(int N) { return N < 5; }
+  int baz(int a)
+    __attribute__((diagnose_if(!supportsAPILevel(10),
+                               "Upgrade to API level 10 to use baz", "error")));
+  int baz(int a)
+    __attribute__((diagnose_if(!a, "0 is not recommended.", "warning")));
+
+  int (*bazptr)(int) = baz; // error: Upgrade to API level 10 to use baz
+  int v = baz(0); // error: Upgrade to API level 10 to use baz
+
+Query for this feature with ``__has_attribute(diagnose_if)``.
+
+
+disable_tail_calls (clang::disable_tail_calls, clang::disable_tail_calls)
+-------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","","","","", "", "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.
+
+
+external_source_symbol (clang::external_source_symbol, clang::external_source_symbol)
+-------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+The ``external_source_symbol`` attribute specifies that a declaration originates
+from an external source and describes the nature of that source.
+
+The fact that Clang is capable of recognizing declarations that were defined
+externally can be used to provide better tooling support for mixed-language
+projects or projects that rely on auto-generated code. For instance, an IDE that
+uses Clang and that supports mixed-language projects can use this attribute to
+provide a correct 'jump-to-definition' feature. For a concrete example,
+consider a protocol that's defined in a Swift file:
+
+.. code-block:: swift
+
+  @objc public protocol SwiftProtocol {
+    func method()
+  }
+
+This protocol can be used from Objective-C code by including a header file that
+was generated by the Swift compiler. The declarations in that header can use
+the ``external_source_symbol`` attribute to make Clang aware of the fact
+that ``SwiftProtocol`` actually originates from a Swift module:
+
+.. code-block:: objc
+
+  __attribute__((external_source_symbol(language="Swift",defined_in="module")))
+  @protocol SwiftProtocol
+  @required
+  - (void) method;
+  @end
+
+Consequently, when 'jump-to-definition' is performed at a location that
+references ``SwiftProtocol``, the IDE can jump to the original definition in
+the Swift source file rather than jumping to the Objective-C declaration in the
+auto-generated header file.
+
+The ``external_source_symbol`` attribute is a comma-separated list that includes
+clauses that describe the origin and the nature of the particular declaration.
+Those clauses can be:
+
+language=\ *string-literal*
+  The name of the source language in which this declaration was defined.
+
+defined_in=\ *string-literal*
+  The name of the source container in which the declaration was defined. The
+  exact definition of source container is language-specific, e.g. Swift's
+  source containers are modules, so ``defined_in`` should specify the Swift
+  module name.
+
+generated_declaration
+  This declaration was automatically generated by some tool.
+
+The clauses can be specified in any order. The clauses that are listed above are
+all optional, but the attribute has to have at least one clause.
+
+
+flatten (gnu::flatten)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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.
+
+
+force_align_arg_pointer (gnu::force_align_arg_pointer)
+------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", ""
+
+Use this attribute to force stack alignment.
+
+Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions
+(like 'movaps') that work with the stack require operands to be 16-byte aligned.
+This attribute realigns the stack in the function prologue to make sure the
+stack can be used with SSE instructions.
+
+Note that the x86_64 ABI forces 16-byte stack alignment at the call site.
+Because of this, 'force_align_arg_pointer' is not needed on x86_64, except in
+rare cases where the caller does not align the stack properly (e.g. flow
+jumps from i386 arch code).
+
+  .. code-block:: c
+
+    __attribute__ ((force_align_arg_pointer))
+    void f () {
+      ...
+    }
+
+
+format (gnu::format)
+--------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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, clang::internal_linkage)
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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 (ARM)
+---------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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.
+
+
+interrupt (AVR)
+---------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+Clang supports the GNU style ``__attribute__((interrupt))`` attribute on
+AVR targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.
+
+On the AVR, the hardware globally disables interrupts when an interrupt is executed.
+The first instruction of an interrupt handler declared with this attribute is a SEI
+instruction to re-enable interrupts. See also the signal attribute that
+does not insert a SEI instruction.
+
+
+interrupt (MIPS)
+----------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "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".
+
+
+interrupt (RISCV)
+-----------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+Clang supports the GNU style ``__attribute__((interrupt))`` attribute on RISCV
+targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be
+used directly as an interrupt service routine.
+
+Permissible values for this parameter are ``user``, ``supervisor``,
+and ``machine``. If there is no parameter, then it defaults to machine.
+
+Repeated interrupt attribute on the same declaration will cause a warning
+to be emitted. In case of repeated declarations, the last one prevails.
+
+Refer to:
+https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Function-Attributes.html
+https://riscv.org/specifications/privileged-isa/
+The RISC-V Instruction Set Manual Volume II: Privileged Architecture
+Version 1.10.
+
+
+kernel
+------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","","","","", "", "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
+
+
+lifetimebound (clang::lifetimebound)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", ""
+
+The ``lifetimebound`` attribute indicates that a resource owned by
+a function parameter or implicit object parameter
+is retained by the return value of the annotated function
+(or, for a parameter of a constructor, in the value of the constructed object).
+It is only supported in C++.
+
+This attribute provides an experimental implementation of the facility
+described in the C++ committee paper [http://wg21.link/p0936r0](P0936R0),
+and is subject to change as the design of the corresponding functionality
+changes.
+
+
+long_call (gnu::long_call, gnu::far)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
+and ``__attribute__((near))`` attributes on MIPS targets. These attributes may
+only be added to function declarations and change the code generated
+by the compiler when directly calling the function. The ``near`` attribute
+allows calls to the function to be made using the ``jal`` instruction, which
+requires the function to be located in the same naturally aligned 256MB
+segment as the caller.  The ``long_call`` and ``far`` attributes are synonyms
+and require the use of a different call sequence that works regardless
+of the distance between the functions.
+
+These attributes have no effect for position-independent code.
+
+These attributes take priority over command line switches such
+as ``-mlong-calls`` and ``-mno-long-calls``.
+
+
+micromips (gnu::micromips)
+--------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+Clang supports the GNU style ``__attribute__((micromips))`` and
+``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
+may be attached to a function definition and instructs the backend to generate
+or not to generate microMIPS code for that function.
+
+These attributes override the `-mmicromips` and `-mno-micromips` options
+on the command line.
+
+
+min_vector_width (clang::min_vector_width, clang::min_vector_width)
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+Clang supports the ``__attribute__((min_vector_width(width)))`` attribute. This
+attribute may be attached to a function and informs the backend that this
+function desires vectors of at least this width to be generated. Target-specific
+maximum vector widths still apply. This means even if you ask for something
+larger than the target supports, you will only get what the target supports.
+This attribute is meant to be a hint to control target heuristics that may
+generate narrower vectors than what the target hardware supports.
+
+This is currently used by the X86 target to allow some CPUs that support 512-bit
+vectors to be limited to using 256-bit vectors to avoid frequency penalties.
+This is currently enabled with the ``-prefer-vector-width=256`` command line
+option. The ``min_vector_width`` attribute can be used to prevent the backend
+from trying to split vector operations to match the ``prefer-vector-width``. All
+X86 vector intrinsics from x86intrin.h already set this attribute. Additionally,
+use of any of the X86-specific vector builtins will implicitly set this
+attribute on the calling function. The intent is that explicitly writing vector
+code using the X86 intrinsics will prevent ``prefer-vector-width`` from
+affecting the code.
+
+
+no_caller_saved_registers (gnu::no_caller_saved_registers)
+----------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", ""
+
+Use this attribute to indicate that the specified function has no
+caller-saved registers. That is, all registers are callee-saved except for
+registers used for passing parameters to the function or returning parameters
+from the function.
+The compiler saves and restores any modified registers that were not used for
+passing or returning arguments to the function.
+
+The user can call functions specified with the 'no_caller_saved_registers'
+attribute from an interrupt handler without saving and restoring all
+call-clobbered registers.
+
+Note that 'no_caller_saved_registers' attribute is not a calling convention.
+In fact, it only overrides the decision of which registers should be saved by
+the caller, but not how the parameters are passed from the caller to the callee.
+
+For example:
+
+  .. code-block:: c
+
+    __attribute__ ((no_caller_saved_registers, fastcall))
+    void f (int arg1, int arg2) {
+      ...
+    }
+
+  In this case parameters 'arg1' and 'arg2' will be passed in registers.
+  In this case, on 32-bit x86 targets, the function 'f' will use ECX and EDX as
+  register parameters. However, it will not assume any scratch registers and
+  should save and restore any modified registers except for ECX and EDX.
+
+
+no_sanitize (clang::no_sanitize, clang::no_sanitize)
+----------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+Use the ``no_sanitize`` attribute on a function or a global variable
+declaration to specify that a particular instrumentation or set of
+instrumentations should not be applied. The attribute takes a list of
+string literals, which have the same meaning as values accepted by the
+``-fno-sanitize=`` flag. For example,
+``__attribute__((no_sanitize("address", "thread")))`` specifies that
+AddressSanitizer and ThreadSanitizer should not be applied to the
+function or variable.
+
+See :ref:`Controlling Code Generation <controlling-code-generation>` for a
+full list of supported sanitizer flags.
+
+
+no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+.. _langext-address_sanitizer:
+
+Use ``__attribute__((no_sanitize_address))`` on a function or a global
+variable declaration to specify that address safety instrumentation
+(e.g. AddressSanitizer) should not be applied.
+
+
+no_sanitize_memory
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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_sanitize_thread
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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_split_stack (gnu::no_split_stack)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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.
+
+
+no_stack_protector (clang::no_stack_protector, clang::no_stack_protector)
+-------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+Clang supports the ``__attribute__((no_stack_protector))`` attribute which disables
+the stack protector on the specified function. This attribute is useful for
+selectively disabling the stack protector on some functions when building with
+``-fstack-protector`` compiler option.
+
+For example, it disables the stack protector for the function ``foo`` but function
+``bar`` will still be built with the stack protector with the ``-fstack-protector``
+option.
+
+.. code-block:: c
+
+    int __attribute__((no_stack_protector))
+    foo (int x); // stack protection will be disabled for foo.
+
+    int bar(int y); // bar can be built with the stack protector.
+
+
+noalias
+-------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","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.
+
+
+nocf_check (gnu::nocf_check)
+----------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+Jump Oriented Programming attacks rely on tampering with addresses used by
+indirect call / jmp, e.g. redirect control-flow to non-programmer
+intended bytes in the binary.
+X86 Supports Indirect Branch Tracking (IBT) as part of Control-Flow
+Enforcement Technology (CET). IBT instruments ENDBR instructions used to
+specify valid targets of indirect call / jmp.
+The ``nocf_check`` attribute has two roles:
+1. Appertains to a function - do not add ENDBR instruction at the beginning of
+the function.
+2. Appertains to a function pointer - do not track the target function of this
+pointer (by adding nocf_check prefix to the indirect-call instruction).
+
+
+nodiscard, warn_unused_result, clang::warn_unused_result, gnu::warn_unused_result
+---------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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.
+
+
+noduplicate (clang::noduplicate, clang::noduplicate)
+----------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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.
+
+
+nomicromips (gnu::nomicromips)
+------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+Clang supports the GNU style ``__attribute__((micromips))`` and
+``__attribute__((nomicromips))`` attributes on MIPS targets. These attributes
+may be attached to a function definition and instructs the backend to generate
+or not to generate microMIPS code for that function.
+
+These attributes override the `-mmicromips` and `-mno-micromips` options
+on the command line.
+
+
+noreturn
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","X","","","", "", "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.
+
+
+not_tail_called (clang::not_tail_called, clang::not_tail_called)
+----------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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;
+    };
+
+
+nothrow (gnu::nothrow)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","X","", "", "X"
+
+Clang supports the GNU style ``__attribute__((nothrow))`` and Microsoft style
+``__declspec(nothrow)`` attribute as an equivalent of `noexcept` on function
+declarations. This attribute informs the compiler that the annotated function
+does not throw an exception. This prevents exception-unwinding. This attribute
+is particularly useful on functions in the C Standard Library that are
+guaranteed to not throw an exception.
+
+
+objc_boxable (clang::objc_boxable, clang::objc_boxable)
+-------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "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 (clang::objc_method_family, clang::objc_method_family)
+-------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "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 (clang::objc_requires_super, clang::objc_requires_super)
+----------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "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 (clang::objc_runtime_name, clang::objc_runtime_name)
+----------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "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 (clang::objc_runtime_visible, clang::objc_runtime_visible)
+-------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "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, clang::optnone)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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 (clang::overloadable, clang::overloadable)
+-------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "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.
+
+* If no viable candidates are otherwise available, we allow a conversion from a
+  pointer of type ``T*`` to a pointer of type ``U*``, where ``T`` and ``U`` are
+  incompatible. This conversion is ranked below all other types of conversions.
+  Please note: ``U`` lacking qualifiers that are present on ``T`` is sufficient
+  for ``T`` and ``U`` to be incompatible.
+
+The declaration of ``overloadable`` functions is restricted to function
+declarations and definitions.  If a function is marked with the ``overloadable``
+attribute, then all declarations and definitions of functions with that name,
+except for at most one (see the note below about unmarked overloads), must have
+the ``overloadable`` attribute.  In addition, redeclarations of a function with
+the ``overloadable`` attribute must have the ``overloadable`` attribute, and
+redeclarations of a function without the ``overloadable`` attribute must *not*
+have the ``overloadable`` attribute. e.g.,
+
+.. code-block:: c
+
+  int f(int) __attribute__((overloadable));
+  float f(float); // error: declaration of "f" must have the "overloadable" attribute
+  int f(int); // error: redeclaration of "f" must have the "overloadable" attribute
+
+  int g(int) __attribute__((overloadable));
+  int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
+
+  int h(int);
+  int h(int) __attribute__((overloadable)); // error: declaration of "h" must not
+                                            // have the "overloadable" attribute
+
+Functions marked ``overloadable`` must have prototypes.  Therefore, the
+following code is ill-formed:
+
+.. code-block:: c
+
+  int h() __attribute__((overloadable)); // error: h does not have a prototype
+
+However, ``overloadable`` functions are allowed to use a ellipsis even if there
+are no named parameters (as is permitted in C++).  This feature is particularly
+useful when combined with the ``unavailable`` attribute:
+
+.. code-block:: c++
+
+  void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
+
+Functions declared with the ``overloadable`` attribute have their names mangled
+according to the same rules as C++ function names.  For example, the three
+``tgsin`` functions in our motivating example get the mangled names
+``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively.  There are two
+caveats to this use of name mangling:
+
+* Future versions of Clang may change the name mangling of functions overloaded
+  in C, so you should not depend on an specific mangling.  To be completely
+  safe, we strongly urge the use of ``static inline`` with ``overloadable``
+  functions.
+
+* The ``overloadable`` attribute has almost no meaning when used in C++,
+  because names will already be mangled and functions are already overloadable.
+  However, when an ``overloadable`` function occurs within an ``extern "C"``
+  linkage specification, it's name *will* be mangled in the same way as it
+  would in C.
+
+For the purpose of backwards compatibility, at most one function with the same
+name as other ``overloadable`` functions may omit the ``overloadable``
+attribute. In this case, the function without the ``overloadable`` attribute
+will not have its name mangled.
+
+For example:
+
+.. code-block:: c
+
+  // Notes with mangled names assume Itanium mangling.
+  int f(int);
+  int f(double) __attribute__((overloadable));
+  void foo() {
+    f(5); // Emits a call to f (not _Z1fi, as it would with an overload that
+          // was marked with overloadable).
+    f(1.0); // Emits a call to _Z1fd.
+  }
+
+Support for unmarked overloads is not present in some versions of clang. You may
+query for it using ``__has_extension(overloadable_unmarked)``.
+
+Query for this attribute with ``__has_attribute(overloadable)``.
+
+
+release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)
+-----------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", ""
+
+Marks a function as releasing a capability.
+
+
+short_call (gnu::short_call, gnu::near)
+---------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+Clang supports the ``__attribute__((long_call))``, ``__attribute__((far))``,
+``__attribute__((short__call))``, and ``__attribute__((near))`` attributes
+on MIPS targets. These attributes may only be added to function declarations
+and change the code generated by the compiler when directly calling
+the function. The ``short_call`` and ``near`` attributes are synonyms and
+allow calls to the function to be made using the ``jal`` instruction, which
+requires the function to be located in the same naturally aligned 256MB segment
+as the caller.  The ``long_call`` and ``far`` attributes are synonyms and
+require the use of a different call sequence that works regardless
+of the distance between the functions.
+
+These attributes have no effect for position-independent code.
+
+These attributes take priority over command line switches such
+as ``-mlong-calls`` and ``-mno-long-calls``.
+
+
+signal (gnu::signal)
+--------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+Clang supports the GNU style ``__attribute__((signal))`` attribute on
+AVR targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.
+
+Interrupt handler functions defined with the signal attribute do not re-enable interrupts.
+
+
+target (gnu::target)
+--------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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.
+
+Additionally, this attribute supports function multiversioning for ELF based
+x86/x86-64 targets, which can be used to create multiple implementations of the
+same function that will be resolved at runtime based on the priority of their
+``target`` attribute strings. A function is considered a multiversioned function
+if either two declarations of the function have different ``target`` attribute
+strings, or if it has a ``target`` attribute string of ``default``.  For
+example:
+
+  .. code-block:: c++
+
+    __attribute__((target("arch=atom")))
+    void foo() {} // will be called on 'atom' processors.
+    __attribute__((target("default")))
+    void foo() {} // will be called on any other processors.
+
+All multiversioned functions must contain a ``default`` (fallback)
+implementation, otherwise usages of the function are considered invalid.
+Additionally, a function may not become multiversioned after its first use.
+
+
+try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)
+---------------------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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).
+
+
+xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument), xray_log_args (clang::xray_log_args)
+--------------------------------------------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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.
+
+``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is used to preserve N function arguments for the logging function.  Currently, only N==1 is supported.
+
+
+xray_always_instrument (clang::xray_always_instrument), xray_never_instrument (clang::xray_never_instrument), xray_log_args (clang::xray_log_args)
+--------------------------------------------------------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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.
+
+``__attribute__((xray_log_args(N)))`` or ``[[clang::xray_log_args(N)]]`` is used to preserve N function arguments for the logging function.  Currently, only N==1 is supported.
+
+
+Variable Attributes
+===================
+
+
+dllexport (gnu::dllexport)
+--------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","", "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
+
+
+maybe_unused, unused, gnu::unused
+---------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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);
+  }
+
+
+nodebug (gnu::nodebug)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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.
+
+
+noescape (clang::noescape, clang::noescape)
+-------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+``noescape`` placed on a function parameter of a pointer type is used to inform
+the compiler that the pointer cannot escape: that is, no reference to the object
+the pointer points to that is derived from the parameter value will survive
+after the function returns. Users are responsible for making sure parameters
+annotated with ``noescape`` do not actuallly escape.
+
+For example:
+
+.. code-block:: c
+
+  int *gp;
+
+  void nonescapingFunc(__attribute__((noescape)) int *p) {
+    *p += 100; // OK.
+  }
+
+  void escapingFunc(__attribute__((noescape)) int *p) {
+    gp = p; // Not OK.
+  }
+
+Additionally, when the parameter is a `block pointer
+<https://clang.llvm.org/docs/BlockLanguageSpec.html>`, the same restriction
+applies to copies of the block. For example:
+
+.. code-block:: c
+
+  typedef void (^BlockTy)();
+  BlockTy g0, g1;
+
+  void nonescapingFunc(__attribute__((noescape)) BlockTy block) {
+    block(); // OK.
+  }
+
+  void escapingFunc(__attribute__((noescape)) BlockTy block) {
+    g0 = block; // Not OK.
+    g1 = Block_copy(block); // Not OK either.
+  }
+
+
+nosvm
+-----
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","","","","", "", "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 (clang::pass_object_size, clang::pass_object_size)
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "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.
+
+
+require_constant_initialization (clang::require_constant_initialization)
+------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+This attribute specifies that the variable to which it is attached is intended
+to have a `constant initializer <http://en.cppreference.com/w/cpp/language/constant_initialization>`_
+according to the rules of [basic.start.static]. The variable is required to
+have static or thread storage duration. If the initialization of the variable
+is not a constant initializer an error will be produced. This attribute may
+only be used in C++.
+
+Note that in C++03 strict constant expression checking is not done. Instead
+the attribute reports if Clang can emit the variable as a constant, even if it's
+not technically a 'constant initializer'. This behavior is non-portable.
+
+Static storage duration variables with constant initializers avoid hard-to-find
+bugs caused by the indeterminate order of dynamic initialization. They can also
+be safely used during dynamic initialization across translation units.
+
+This attribute acts as a compile time assertion that the requirements
+for constant initialization have been met. Since these requirements change
+between dialects and have subtle pitfalls it's important to fail fast instead
+of silently falling back on dynamic initialization.
+
+.. code-block:: c++
+
+  // -std=c++14
+  #define SAFE_STATIC [[clang::require_constant_initialization]]
+  struct T {
+    constexpr T(int) {}
+    ~T(); // non-trivial
+  };
+  SAFE_STATIC T x = {42}; // Initialization OK. Doesn't check destructor.
+  SAFE_STATIC T y = 42; // error: variable does not have a constant initializer
+  // copy initialization is not a constant expression on a non-literal type.
+
+
+section (gnu::section, __declspec(allocate))
+--------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","X","", "", "X"
+
+The ``section`` attribute allows you to specify a specific section a
+global variable or function should be in after translation.
+
+
+swift_context (clang::swift_context, clang::swift_context)
+----------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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 (clang::swift_error_result, clang::swift_error_result)
+-------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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 (clang::swift_indirect_result, clang::swift_indirect_result)
+----------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+The ``swift_indirect_result`` attribute marks a parameter of a ``swiftcall``
+function as having the special indirect-result ABI treatment.
+
+This treatment gives the parameter the target's normal indirect-result
+ABI treatment, which may involve passing it differently from an ordinary
+parameter.  However, only the first indirect result will receive this
+treatment.  Furthermore, low-level lowering may decide that a direct result
+must be returned indirectly; if so, this will take priority over the
+``swift_indirect_result`` parameters.
+
+A ``swift_indirect_result`` parameter must either be the first parameter or
+follow another ``swift_indirect_result`` parameter.
+
+A ``swift_indirect_result`` parameter must have type ``T*`` or ``T&`` for
+some object type ``T``.  If ``T`` is a complete type at the point of
+definition of a function, it is undefined behavior if the argument
+value does not point to storage of adequate size and alignment for a
+value of type ``T``.
+
+Making indirect results explicit in the signature allows C functions to
+directly construct objects into them without relying on language
+optimizations like C++'s named return value optimization (NRVO).
+
+
+swiftcall (clang::swiftcall, clang::swiftcall)
+----------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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.
+
+
+thread
+------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","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.
+
+
+tls_model (gnu::tls_model)
+--------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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.
+
+
+trivial_abi (clang::trivial_abi)
+--------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+The ``trivial_abi`` attribute can be applied to a C++ class, struct, or union.
+It instructs the compiler to pass and return the type using the C ABI for the
+underlying type when the type would otherwise be considered non-trivial for the
+purpose of calls.
+A class annotated with `trivial_abi` can have non-trivial destructors or copy/move constructors without automatically becoming non-trivial for the purposes of calls. For example:
+
+  .. code-block:: c++
+
+    // A is trivial for the purposes of calls because `trivial_abi` makes the
+    // user-provided special functions trivial.
+    struct __attribute__((trivial_abi)) A {
+      ~A();
+      A(const A &);
+      A(A &&);
+      int x;
+    };
+
+    // B's destructor and copy/move constructor are considered trivial for the
+    // purpose of calls because A is trivial.
+    struct B {
+      A a;
+    };
+
+If a type is trivial for the purposes of calls, has a non-trivial destructor,
+and is passed as an argument by value, the convention is that the callee will
+destroy the object before returning.
+
+Attribute ``trivial_abi`` has no effect in the following cases:
+
+- The class directly declares a virtual base or virtual methods.
+- The class has a base class that is non-trivial for the purposes of calls.
+- The class has a non-static data member whose type is non-trivial for the purposes of calls, which includes:
+
+  - classes that are non-trivial for the purposes of calls
+  - __weak-qualified types in Objective-C++
+  - arrays of any of the above
+
+
+Type Attributes
+===============
+
+
+__single_inhertiance, __multiple_inheritance, __virtual_inheritance
+-------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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 {};
+
+
+align_value
+-----------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","","","","", "", "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","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.
+
+
+enum_extensibility (clang::enum_extensibility, clang::enum_extensibility)
+-------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+Attribute ``enum_extensibility`` is used to distinguish between enum definitions
+that are extensible and those that are not. The attribute can take either
+``closed`` or ``open`` as an argument. ``closed`` indicates a variable of the
+enum type takes a value that corresponds to one of the enumerators listed in the
+enum definition or, when the enum is annotated with ``flag_enum``, a value that
+can be constructed using values corresponding to the enumerators. ``open``
+indicates a variable of the enum type can take any values allowed by the
+standard and instructs clang to be more lenient when issuing warnings.
+
+.. code-block:: c
+
+  enum __attribute__((enum_extensibility(closed))) ClosedEnum {
+    A0, A1
+  };
+
+  enum __attribute__((enum_extensibility(open))) OpenEnum {
+    B0, B1
+  };
+
+  enum __attribute__((enum_extensibility(closed),flag_enum)) ClosedFlagEnum {
+    C0 = 1 << 0, C1 = 1 << 1
+  };
+
+  enum __attribute__((enum_extensibility(open),flag_enum)) OpenFlagEnum {
+    D0 = 1 << 0, D1 = 1 << 1
+  };
+
+  void foo1() {
+    enum ClosedEnum ce;
+    enum OpenEnum oe;
+    enum ClosedFlagEnum cfe;
+    enum OpenFlagEnum ofe;
+
+    ce = A1;           // no warnings
+    ce = 100;          // warning issued
+    oe = B1;           // no warnings
+    oe = 100;          // no warnings
+    cfe = C0 | C1;     // no warnings
+    cfe = C0 | C1 | 4; // warning issued
+    ofe = D0 | D1;     // no warnings
+    ofe = D0 | D1 | 4; // no warnings
+  }
+
+
+flag_enum (clang::flag_enum, clang::flag_enum)
+----------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "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.
+
+
+layout_version
+--------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","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.
+
+
+lto_visibility_public (clang::lto_visibility_public, clang::lto_visibility_public)
+----------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+See :doc:`LTOVisibility`.
+
+
+novtable
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","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.
+
+
+objc_subclassing_restricted (clang::objc_subclassing_restricted, clang::objc_subclassing_restricted)
+----------------------------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", "X"
+
+This attribute can be added to an Objective-C ``@interface`` declaration to
+ensure that this class cannot be subclassed.
+
+
+selectany (gnu::selectany)
+--------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","X","", "", ""
+
+This attribute appertains to a global symbol, causing it to have a weak
+definition (
+`linkonce <https://llvm.org/docs/LangRef.html#linkage-types>`_
+), allowing the linker to select any definition.
+
+For more information see
+`gcc documentation <https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html>`_
+or `msvc documentation <https://docs.microsoft.com/pl-pl/cpp/cpp/selectany>`_.
+
+
+transparent_union (gnu::transparent_union)
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", ""
+
+This attribute can be applied to a union to change the behaviour of calls to
+functions that have an argument with a transparent union type. The compiler
+behaviour is changed in the following manner:
+
+- A value whose type is any member of the transparent union can be passed as an
+  argument without the need to cast that value.
+
+- The argument is passed to the function using the calling convention of the
+  first member of the transparent union. Consequently, all the members of the
+  transparent union should have the same calling convention as its first member.
+
+Transparent unions are not supported in C++.
+
+
+Statement Attributes
+====================
+
+
+#pragma clang loop
+------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","", "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","", "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.
+
+
+__attribute__((intel_reqd_sub_group_size))
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","","","","", "", "X"
+
+The optional attribute intel_reqd_sub_group_size can be used to indicate that
+the kernel must be compiled and executed with the specified subgroup size. When
+this attribute is present, get_max_sub_group_size() is guaranteed to return the
+specified integer value. This is important for the correctness of many subgroup
+algorithms, and in some cases may be used by the compiler to generate more optimal
+code. See `cl_intel_required_subgroup_size
+<https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_required_subgroup_size.txt>`
+for details.
+
+
+__attribute__((opencl_unroll_hint))
+-----------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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.
+
+
+__read_only, __write_only, __read_write (read_only, write_only, read_write)
+---------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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.
+
+
+fallthrough, clang::fallthrough
+-------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","X","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();
+  }
+
+
+suppress (gsl::suppress)
+------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","X","","","", "", ""
+
+The ``[[gsl::suppress]]`` attribute suppresses specific
+clang-tidy diagnostics for rules of the `C++ Core Guidelines`_ in a portable
+way. The attribute can be attached to declarations, statements, and at
+namespace scope.
+
+.. code-block:: c++
+
+  [[gsl::suppress("Rh-public")]]
+  void f_() {
+    int *p;
+    [[gsl::suppress("type")]] {
+      p = reinterpret_cast<int*>(7);
+    }
+  }
+  namespace N {
+    [[clang::suppress("type", "bounds")]];
+    ...
+  }
+
+.. _`C++ Core Guidelines`: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#inforce-enforcement
+
+
+AMD GPU Attributes
+==================
+
+
+amdgpu_flat_work_group_size (clang::amdgpu_flat_work_group_size)
+----------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+The flat work-group size is the number of work-items in the work-group size
+specified when the kernel is dispatched. It is the product of the sizes of the
+x, y, and z dimension of the work-group.
+
+Clang supports the
+``__attribute__((amdgpu_flat_work_group_size(<min>, <max>)))`` attribute for the
+AMDGPU target. This attribute may be attached to a kernel function definition
+and is an optimization hint.
+
+``<min>`` parameter specifies the minimum flat work-group size, and ``<max>``
+parameter specifies the maximum flat work-group size (must be greater than
+``<min>``) to which all dispatches of the kernel will conform. Passing ``0, 0``
+as ``<min>, <max>`` implies the default behavior (``128, 256``).
+
+If specified, the AMDGPU target backend might be able to produce better machine
+code for barriers and perform scratch promotion by estimating available group
+segment size.
+
+An error will be given if:
+  - Specified values violate subtarget specifications;
+  - Specified values are not compatible with values provided through other
+    attributes.
+
+
+amdgpu_num_sgpr (clang::amdgpu_num_sgpr)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
+``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.
+
+If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing ``0`` as
+``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
+
+These attributes can be used to test the AMDGPU target backend. It is
+recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.
+
+An error will be given if:
+  - Specified values violate subtarget specifications;
+  - Specified values are not compatible with values provided through other
+    attributes;
+  - The AMDGPU target backend is unable to create machine code that can meet the
+    request.
+
+
+amdgpu_num_vgpr (clang::amdgpu_num_vgpr)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+Clang supports the ``__attribute__((amdgpu_num_sgpr(<num_sgpr>)))`` and
+``__attribute__((amdgpu_num_vgpr(<num_vgpr>)))`` attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.
+
+If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing ``0`` as
+``num_sgpr`` and/or ``num_vgpr`` implies the default behavior (no limits).
+
+These attributes can be used to test the AMDGPU target backend. It is
+recommended that the ``amdgpu_waves_per_eu`` attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.
+
+An error will be given if:
+  - Specified values violate subtarget specifications;
+  - Specified values are not compatible with values provided through other
+    attributes;
+  - The AMDGPU target backend is unable to create machine code that can meet the
+    request.
+
+
+amdgpu_waves_per_eu (clang::amdgpu_waves_per_eu)
+------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "X"
+
+A compute unit (CU) is responsible for executing the wavefronts of a work-group.
+It is composed of one or more execution units (EU), which are responsible for
+executing the wavefronts. An EU can have enough resources to maintain the state
+of more than one executing wavefront. This allows an EU to hide latency by
+switching between wavefronts in a similar way to symmetric multithreading on a
+CPU. In order to allow the state for multiple wavefronts to fit on an EU, the
+resources used by a single wavefront have to be limited. For example, the number
+of SGPRs and VGPRs. Limiting such resources can allow greater latency hiding,
+but can result in having to spill some register state to memory.
+
+Clang supports the ``__attribute__((amdgpu_waves_per_eu(<min>[, <max>])))``
+attribute for the AMDGPU target. This attribute may be attached to a kernel
+function definition and is an optimization hint.
+
+``<min>`` parameter specifies the requested minimum number of waves per EU, and
+*optional* ``<max>`` parameter specifies the requested maximum number of waves
+per EU (must be greater than ``<min>`` if specified). If ``<max>`` is omitted,
+then there is no restriction on the maximum number of waves per EU other than
+the one dictated by the hardware for which the kernel is compiled. Passing
+``0, 0`` as ``<min>, <max>`` implies the default behavior (no limits).
+
+If specified, this attribute allows an advanced developer to tune the number of
+wavefronts that are capable of fitting within the resources of an EU. The AMDGPU
+target backend can use this information to limit resources, such as number of
+SGPRs, number of VGPRs, size of available group and private memory segments, in
+such a way that guarantees that at least ``<min>`` wavefronts and at most
+``<max>`` wavefronts are able to fit within the resources of an EU. Requesting
+more wavefronts can hide memory latency but limits available registers which
+can result in spilling. Requesting fewer wavefronts can help reduce cache
+thrashing, but can reduce memory latency hiding.
+
+This attribute controls the machine code generated by the AMDGPU target backend
+to ensure it is capable of meeting the requested values. However, when the
+kernel is executed, there may be other reasons that prevent meeting the request,
+for example, there may be wavefronts from other kernels executing on the EU.
+
+An error will be given if:
+  - Specified values violate subtarget specifications;
+  - Specified values are not compatible with values provided through other
+    attributes;
+  - The AMDGPU target backend is unable to create machine code that can meet the
+    request.
+
+
+Calling Conventions
+===================
+Clang supports several different calling conventions, depending on the target
+platform and architecture. The calling convention used for a function determines
+how parameters are passed, how results are returned to the caller, and other
+low-level details of calling a function.
+
+fastcall (gnu::fastcall, __fastcall, _fastcall)
+-----------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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 (clang::preserve_all, clang::preserve_all)
+-------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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 (clang::preserve_most, clang::preserve_most)
+----------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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.
+
+
+regcall (gnu::regcall, __regcall)
+---------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","X", "", ""
+
+On x86 targets, this attribute changes the calling convention to
+`__regcall`_ convention. This convention aims to pass as many arguments
+as possible in registers. It also tries to utilize registers for the
+return value whenever it is possible.
+
+.. _`__regcall`: https://software.intel.com/en-us/node/693069
+
+
+regparm (gnu::regparm)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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 (clang::vectorcall, clang::vectorcall, __vectorcall, _vectorcall)
+----------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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. Homogeneous vector aggregates of up to four elements are
+passed in sequential SSE registers if enough are available. If AVX is enabled,
+256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that
+cannot be passed in registers for any reason is passed by reference, which
+allows the caller to align the parameter memory.
+
+See the documentation for `__vectorcall`_ on MSDN for more details.
+
+.. _`__vectorcall`: http://msdn.microsoft.com/en-us/library/dn375768.aspx
+
+
+Consumed Annotation Checking
+============================
+Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although **the implementation
+for these annotations is currently in development and are subject to change.**
+
+callable_when (clang::callable_when)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "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 (clang::consumable)
+------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "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 (clang::param_typestate)
+----------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "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 (clang::return_typestate)
+------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "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 (clang::set_typestate)
+------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "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 (clang::test_typestate)
+--------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","","","", "", "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. To see warnings produced by these
+checks, ensure that -Wtype-safety is enabled. Use cases include:
+
+* MPI library implementations, where these attributes enable checking that
+  the buffer type matches the passed ``MPI_Datatype``;
+* for HDF5 library there is a similar use case to MPI;
+* checking types of variadic functions' arguments for functions like
+  ``fcntl()`` and ``ioctl()``.
+
+You can detect support for these attributes with ``__has_attribute()``.  For
+example:
+
+.. code-block:: c++
+
+  #if defined(__has_attribute)
+  #  if __has_attribute(argument_with_type_tag) && \
+        __has_attribute(pointer_with_type_tag) && \
+        __has_attribute(type_tag_for_datatype)
+  #    define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
+  /* ... other macros ...  */
+  #  endif
+  #endif
+
+  #if !defined(ATTR_MPI_PWT)
+  # define ATTR_MPI_PWT(buffer_idx, type_idx)
+  #endif
+
+  int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+      ATTR_MPI_PWT(1,3);
+
+argument_with_type_tag
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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.
+
+This attribute is primarily useful for checking arguments of variadic functions
+(``pointer_with_type_tag`` can be used in most non-variadic cases).
+
+In the attribute prototype above:
+  * ``arg_kind`` is an identifier that should be used when annotating all
+    applicable type tags.
+  * ``arg_idx`` provides the position of a function argument. The expected type of
+    this function argument will be determined by the function argument specified
+    by ``type_tag_idx``. In the code example below, "3" means that the type of the
+    function's third argument will be determined by ``type_tag_idx``.
+  * ``type_tag_idx`` provides the position of a function argument. This function
+    argument will be a type tag. The type tag will determine the expected type of
+    the argument specified by ``arg_idx``. In the code example below, "2" means
+    that the type tag associated with the function's second argument should agree
+    with the type of the argument specified by ``arg_idx``.
+
+For example:
+
+.. code-block:: c++
+
+  int fcntl(int fd, int cmd, ...)
+      __attribute__(( argument_with_type_tag(fcntl,3,2) ));
+  // The function's second argument will be a type tag; this type tag will
+  // determine the expected type of the function's third argument.
+
+
+pointer_with_type_tag
+---------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","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.
+
+In the attribute prototype above:
+  * ``ptr_kind`` is an identifier that should be used when annotating all
+    applicable type tags.
+  * ``ptr_idx`` provides the position of a function argument; this function
+    argument will have a pointer type. The expected pointee type of this pointer
+    type will be determined by the function argument specified by
+    ``type_tag_idx``. In the code example below, "1" means that the pointee type
+    of the function's first argument will be determined by ``type_tag_idx``.
+  * ``type_tag_idx`` provides the position of a function argument; this function
+    argument will be a type tag. The type tag will determine the expected pointee
+    type of the pointer argument specified by ``ptr_idx``. In the code example
+    below, "3" means that the type tag associated with the function's third
+    argument should agree with the pointee type of the pointer argument specified
+    by ``ptr_idx``.
+
+For example:
+
+.. code-block:: c++
+
+  typedef int MPI_Datatype;
+  int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+      __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+  // The function's 3rd argument will be a type tag; this type tag will
+  // determine the expected pointee type of the function's 1st argument.
+
+
+type_tag_for_datatype (clang::type_tag_for_datatype, clang::type_tag_for_datatype)
+----------------------------------------------------------------------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","X","X","","", "", ""
+
+When declaring a variable, use
+``__attribute__((type_tag_for_datatype(kind, type)))`` to create a type tag that
+is tied to the ``type`` argument given to the attribute.
+
+In the attribute prototype above:
+  * ``kind`` is an identifier that should be used when annotating all applicable
+    type tags.
+  * ``type`` indicates the name of the type.
+
+Clang supports annotating type tags of two forms.
+
+  * **Type tag that is a reference to a declared identifier.**
+    Use ``__attribute__((type_tag_for_datatype(kind, type)))`` when declaring that
+    identifier:
+
+    .. code-block:: c++
+
+      typedef int MPI_Datatype;
+      extern struct mpi_datatype mpi_datatype_int
+          __attribute__(( type_tag_for_datatype(mpi,int) ));
+      #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
+      // &mpi_datatype_int is a type tag. It is tied to type "int".
+
+  * **Type tag that is an integral literal.**
+    Declare a ``static const`` variable with an initializer value and attach
+    ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration:
+
+    .. code-block:: c++
+
+      typedef int MPI_Datatype;
+      static const MPI_Datatype mpi_datatype_int
+          __attribute__(( type_tag_for_datatype(mpi,int) )) = 42;
+      #define MPI_INT ((MPI_Datatype) 42)
+      // The number 42 is a type tag. It is tied to type "int".
+
+
+The ``type_tag_for_datatype`` attribute also accepts an optional third argument
+that determines how the type of the function argument specified by either
+``arg_idx`` or ``ptr_idx`` is compared against the type associated with the type
+tag. (Recall that for the ``argument_with_type_tag`` attribute, the type of the
+function argument specified by ``arg_idx`` is compared against the type
+associated with the type tag. Also recall that for the ``pointer_with_type_tag``
+attribute, the pointee type of the function argument specified by ``ptr_idx`` is
+compared against the type associated with the type tag.) There are two supported
+values for this optional third argument:
+
+  * ``layout_compatible`` will cause types to be compared according to
+    layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the
+    layout-compatibility rules for two standard-layout struct types and for two
+    standard-layout union types). This is useful when creating a type tag
+    associated with a struct or union type. For example:
+
+    .. code-block:: c++
+
+      /* In mpi.h */
+      typedef int MPI_Datatype;
+      struct internal_mpi_double_int { double d; int i; };
+      extern struct mpi_datatype mpi_datatype_double_int
+          __attribute__(( type_tag_for_datatype(mpi,
+                          struct internal_mpi_double_int, layout_compatible) ));
+
+      #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
+
+      int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
+          __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+      /* In user code */
+      struct my_pair { double a; int b; };
+      struct my_pair *buffer;
+      MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ...  */); // no warning because the
+                                                       // layout of my_pair is
+                                                       // compatible with that of
+                                                       // internal_mpi_double_int
+
+      struct my_int_pair { int a; int b; }
+      struct my_int_pair *buffer2;
+      MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ...  */); // warning because the
+                                                        // layout of my_int_pair
+                                                        // does not match that of
+                                                        // internal_mpi_double_int
+
+  * ``must_be_null`` specifies that the function argument specified by either
+    ``arg_idx`` (for the ``argument_with_type_tag`` attribute) or ``ptr_idx`` (for
+    the ``pointer_with_type_tag`` attribute) should be a null pointer constant.
+    The second argument to the ``type_tag_for_datatype`` attribute is ignored. For
+    example:
+
+    .. code-block:: c++
+
+      /* In mpi.h */
+      typedef int MPI_Datatype;
+      extern struct mpi_datatype mpi_datatype_null
+          __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
+
+      #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
+      int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
+          __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+      /* In user code */
+      struct my_pair { double a; int b; };
+      struct my_pair *buffer;
+      MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ...  */); // warning: MPI_DATATYPE_NULL
+                                                          // was specified but buffer
+                                                          // is not a null pointer
+
+
+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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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
+--------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "","","","","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.
+
+
+nonnull (gnu::nonnull)
+----------------------
+.. csv-table:: Supported Syntaxes
+   :header: "GNU", "C++11", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "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", "C2x", "__declspec", "Keyword", "Pragma", "Pragma clang attribute"
+
+   "X","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
+
+

Added: www-releases/trunk/7.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/AutomaticReferenceCounting.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,2326 @@
+.. 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_reference_unavailable`` attribute on the class's interface declaration.  A
+retainable object pointer type is **weak-unavailable** if
+is a pointer to an (optionally protocol-qualified) Objective-C class ``T`` where
+``T`` or one of its superclasses has the ``objc_arc_weak_reference_unavailable``
+attribute.  A program is ill-formed if it applies the ``__weak`` ownership
+qualifier to a weak-unavailable type or if the value operand of a weak
+assignment operation has a weak-unavailable type.
+
+.. _arc.ownership.restrictions.autoreleasing:
+
+Storage duration of ``__autoreleasing`` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it declares an ``__autoreleasing`` object of
+non-automatic storage duration.  A program is ill-formed if it captures an
+``__autoreleasing`` object in a block or, unless by reference, in a C++11
+lambda.
+
+.. admonition:: Rationale
+
+  Autorelease pools are tied to the current thread and scope by their nature.
+  While it is possible to have temporary objects whose instance variables are
+  filled with autoreleased objects, there is no way that ARC can provide any
+  sort of safety guarantee there.
+
+It is undefined behavior if a non-null pointer is assigned to an
+``__autoreleasing`` object while an autorelease pool is in scope and then that
+object is read after the autorelease pool's scope is left.
+
+.. _arc.ownership.restrictions.conversion.indirect:
+
+Conversion of pointers to ownership-qualified types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if an expression of type ``T*`` is converted,
+explicitly or implicitly, to the type ``U*``, where ``T`` and ``U`` have
+different ownership qualification, unless:
+
+* ``T`` is qualified with ``__strong``, ``__autoreleasing``, or
+  ``__unsafe_unretained``, and ``U`` is qualified with both ``const`` and
+  ``__unsafe_unretained``; or
+* either ``T`` or ``U`` is ``cv void``, where ``cv`` is an optional sequence
+  of non-ownership qualifiers; or
+* the conversion is requested with a ``reinterpret_cast`` in Objective-C++; or
+* the conversion is a well-formed :ref:`pass-by-writeback
+  <arc.ownership.restrictions.pass_by_writeback>`.
+
+The analogous rule applies to ``T&`` and ``U&`` in Objective-C++.
+
+.. admonition:: Rationale
+
+  These rules provide a reasonable level of type-safety for indirect pointers,
+  as long as the underlying memory is not deallocated.  The conversion to
+  ``const __unsafe_unretained`` is permitted because the semantics of reads are
+  equivalent across all these ownership semantics, and that's a very useful and
+  common pattern.  The interconversion with ``void*`` is useful for allocating
+  memory or otherwise escaping the type system, but use it carefully.
+  ``reinterpret_cast`` is considered to be an obvious enough sign of taking
+  responsibility for any problems.
+
+It is undefined behavior to access an ownership-qualified object through an
+lvalue of a differently-qualified type, except that any non-``__weak`` object
+may be read through an ``__unsafe_unretained`` lvalue.
+
+It is undefined behavior if the storage of a ``__strong`` or ``__weak``
+object is not properly initialized before the first managed operation
+is performed on the object, or if the storage of such an object is freed
+or reused before the object has been properly deinitialized.  Storage for
+a ``__strong`` or ``__weak`` object may be properly initialized by filling
+it with the representation of a null pointer, e.g. by acquiring the memory
+with ``calloc`` or using ``bzero`` to zero it out.  A ``__strong`` or
+``__weak`` object may be properly deinitialized by assigning a null pointer
+into it.  A ``__strong`` object may also be properly initialized
+by copying into it (e.g. with ``memcpy``) the representation of a
+different ``__strong`` object whose storage has been properly initialized;
+doing this properly deinitializes the source object and causes its storage
+to no longer be properly initialized.  A ``__weak`` object may not be
+representation-copied in this way.
+
+These requirements are followed automatically for objects whose
+initialization and deinitialization are under the control of ARC:
+
+* objects of static, automatic, and temporary storage duration
+* instance variables of Objective-C objects
+* elements of arrays where the array object's initialization and
+  deinitialization are under the control of ARC
+* fields of Objective-C struct types where the struct object's
+  initialization and deinitialization are under the control of ARC
+* non-static data members of Objective-C++ non-union class types
+* Objective-C++ objects and arrays of dynamic storage duration created
+  with the ``new`` or ``new[]`` operators and destroyed with the
+  corresponding ``delete`` or ``delete[]`` operator
+
+They are not followed automatically for these objects:
+
+* objects of dynamic storage duration created in other memory, such as
+  that returned by ``malloc``
+* union members
+
+.. admonition:: Rationale
+
+  ARC must perform special operations when initializing an object and
+  when destroying it.  In many common situations, ARC knows when an
+  object is created and when it is destroyed and can ensure that these
+  operations are performed correctly.  Otherwise, however, ARC requires
+  programmer cooperation to establish its initialization invariants
+  because it is infeasible for ARC to dynamically infer whether they
+  are intact.  For example, there is no syntactic difference in C between
+  an assignment that is intended by the programmer to initialize a variable
+  and one that is intended to replace the existing value stored there,
+  but ARC must perform one operation or the other.  ARC chooses to always
+  assume that objects are initialized (except when it is in charge of
+  initializing them) because the only workable alternative would be to
+  ban all code patterns that could potentially be used to access
+  uninitialized memory, and that would be too limiting.  In practice,
+  this is rarely a problem because programmers do not generally need to
+  work with objects for which the requirements are not handled
+  automatically.
+
+Note that dynamically-allocated Objective-C++ arrays of
+nontrivially-ownership-qualified type are not ABI-compatible with non-ARC
+code because the non-ARC code will consider the element type to be POD.
+Such arrays that are ``new[]``'d in ARC translation units cannot be
+``delete[]``'d in non-ARC translation units and vice-versa.
+
+.. _arc.ownership.restrictions.pass_by_writeback:
+
+Passing to an out parameter by writeback
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the argument passed to a parameter of type ``T __autoreleasing *`` has type
+``U oq *``, where ``oq`` is an ownership qualifier, then the argument is a
+candidate for :arc-term:`pass-by-writeback`` if:
+
+* ``oq`` is ``__strong`` or ``__weak``, and
+* it would be legal to initialize a ``T __strong *`` with a ``U __strong *``.
+
+For purposes of overload resolution, an implicit conversion sequence requiring
+a pass-by-writeback is always worse than an implicit conversion sequence not
+requiring a pass-by-writeback.
+
+The pass-by-writeback is ill-formed if the argument expression does not have a
+legal form:
+
+* ``&var``, where ``var`` is a scalar variable of automatic storage duration
+  with retainable object pointer type
+* a conditional expression where the second and third operands are both legal
+  forms
+* a cast whose operand is a legal form
+* a null pointer constant
+
+.. admonition:: Rationale
+
+  The restriction in the form of the argument serves two purposes.  First, it
+  makes it impossible to pass the address of an array to the argument, which
+  serves to protect against an otherwise serious risk of mis-inferring an
+  "array" argument as an out-parameter.  Second, it makes it much less likely
+  that the user will see confusing aliasing problems due to the implementation,
+  below, where their store to the writeback temporary is not immediately seen
+  in the original argument variable.
+
+A pass-by-writeback is evaluated as follows:
+
+#. The argument is evaluated to yield a pointer ``p`` of type ``U oq *``.
+#. If ``p`` is a null pointer, then a null pointer is passed as the argument,
+   and no further work is required for the pass-by-writeback.
+#. Otherwise, a temporary of type ``T __autoreleasing`` is created and
+   initialized to a null pointer.
+#. If the parameter is not an Objective-C method parameter marked ``out``,
+   then ``*p`` is read, and the result is written into the temporary with
+   primitive semantics.
+#. The address of the temporary is passed as the argument to the actual call.
+#. After the call completes, the temporary is loaded with primitive
+   semantics, and that value is assigned into ``*p``.
+
+.. admonition:: Rationale
+
+  This is all admittedly convoluted.  In an ideal world, we would see that a
+  local variable is being passed to an out-parameter and retroactively modify
+  its type to be ``__autoreleasing`` rather than ``__strong``.  This would be
+  remarkably difficult and not always well-founded under the C type system.
+  However, it was judged unacceptably invasive to require programmers to write
+  ``__autoreleasing`` on all the variables they intend to use for
+  out-parameters.  This was the least bad solution.
+
+.. _arc.ownership.restrictions.records:
+
+Ownership-qualified fields of structs and unions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it declares a member of a C struct or union to have
+a nontrivially ownership-qualified type.
+
+.. admonition:: Rationale
+
+  The resulting type would be non-POD in the C++ sense, but C does not give us
+  very good language tools for managing the lifetime of aggregates, so it is
+  more convenient to simply forbid them.  It is still possible to manage this
+  with a ``void*`` or an ``__unsafe_unretained`` object.
+
+This restriction does not apply in Objective-C++.  However, nontrivally
+ownership-qualified types are considered non-POD: in C++11 terms, they are not
+trivially default constructible, copy constructible, move constructible, copy
+assignable, move assignable, or destructible.  It is a violation of C++'s One
+Definition Rule to use a class outside of ARC that, under ARC, would have a
+nontrivially ownership-qualified member.
+
+.. admonition:: Rationale
+
+  Unlike in C, we can express all the necessary ARC semantics for
+  ownership-qualified subobjects as suboperations of the (default) special
+  member functions for the class.  These functions then become non-trivial.
+  This has the non-obvious result that the class will have a non-trivial copy
+  constructor and non-trivial destructor; if this would not normally be true
+  outside of ARC, objects of the type will be passed and returned in an
+  ABI-incompatible manner.
+
+.. _arc.ownership.inference:
+
+Ownership inference
+-------------------
+
+.. _arc.ownership.inference.variables:
+
+Objects
+^^^^^^^
+
+If an object is declared with retainable object owner type, but without an
+explicit ownership qualifier, its type is implicitly adjusted to have
+``__strong`` qualification.
+
+As a special case, if the object's base type is ``Class`` (possibly
+protocol-qualified), the type is adjusted to have ``__unsafe_unretained``
+qualification instead.
+
+.. _arc.ownership.inference.indirect_parameters:
+
+Indirect parameters
+^^^^^^^^^^^^^^^^^^^
+
+If a function or method parameter has type ``T*``, where ``T`` is an
+ownership-unqualified retainable object pointer type, then:
+
+* if ``T`` is ``const``-qualified or ``Class``, then it is implicitly
+  qualified with ``__unsafe_unretained``;
+* otherwise, it is implicitly qualified with ``__autoreleasing``.
+
+.. admonition:: Rationale
+
+  ``__autoreleasing`` exists mostly for this case, the Cocoa convention for
+  out-parameters.  Since a pointer to ``const`` is obviously not an
+  out-parameter, we instead use a type more useful for passing arrays.  If the
+  user instead intends to pass in a *mutable* array, inferring
+  ``__autoreleasing`` is the wrong thing to do; this directs some of the
+  caution in the following rules about writeback.
+
+Such a type written anywhere else would be ill-formed by the general rule
+requiring ownership qualifiers.
+
+This rule does not apply in Objective-C++ if a parameter's type is dependent in
+a template pattern and is only *instantiated* to a type which would be a
+pointer to an unqualified retainable object pointer type.  Such code is still
+ill-formed.
+
+.. admonition:: Rationale
+
+  The convention is very unlikely to be intentional in template code.
+
+.. _arc.ownership.inference.template.arguments:
+
+Template arguments
+^^^^^^^^^^^^^^^^^^
+
+If a template argument for a template type parameter is an retainable object
+owner type that does not have an explicit ownership qualifier, it is adjusted
+to have ``__strong`` qualification.  This adjustment occurs regardless of
+whether the template argument was deduced or explicitly specified.
+
+.. admonition:: Rationale
+
+  ``__strong`` is a useful default for containers (e.g., ``std::vector<id>``),
+  which would otherwise require explicit qualification.  Moreover, unqualified
+  retainable object pointer types are unlikely to be useful within templates,
+  since they generally need to have a qualifier applied to the before being
+  used.
+
+.. _arc.method-families:
+
+Method families
+===============
+
+An Objective-C method may fall into a :arc-term:`method family`, which is a
+conventional set of behaviors ascribed to it by the Cocoa conventions.
+
+A method is in a certain method family if:
+
+* it has a ``objc_method_family`` attribute placing it in that family; or if
+  not that,
+* it does not have an ``objc_method_family`` attribute placing it in a
+  different or no family, and
+* its selector falls into the corresponding selector family, and
+* its signature obeys the added restrictions of the method family.
+
+A selector is in a certain selector family if, ignoring any leading
+underscores, the first component of the selector either consists entirely of
+the name of the method family or it begins with that name followed by a
+character other than a lowercase letter.  For example, ``_perform:with:`` and
+``performWith:`` would fall into the ``perform`` family (if we recognized one),
+but ``performing:with`` would not.
+
+The families and their added restrictions are:
+
+* ``alloc`` methods must return a retainable object pointer type.
+* ``copy`` methods must return a retainable object pointer type.
+* ``mutableCopy`` methods must return a retainable object pointer type.
+* ``new`` methods must return a retainable object pointer type.
+* ``init`` methods must be instance methods and must return an Objective-C
+  pointer type.  Additionally, a program is ill-formed if it declares or
+  contains a call to an ``init`` method whose return type is neither ``id`` nor
+  a pointer to a super-class or sub-class of the declaring class (if the method
+  was declared on a class) or the static receiver type of the call (if it was
+  declared on a protocol).
+
+  .. admonition:: Rationale
+
+    There are a fair number of existing methods with ``init``-like selectors
+    which nonetheless don't follow the ``init`` conventions.  Typically these
+    are either accidental naming collisions or helper methods called during
+    initialization.  Because of the peculiar retain/release behavior of
+    ``init`` methods, it's very important not to treat these methods as
+    ``init`` methods if they aren't meant to be.  It was felt that implicitly
+    defining these methods out of the family based on the exact relationship
+    between the return type and the declaring class would be much too subtle
+    and fragile.  Therefore we identify a small number of legitimate-seeming
+    return types and call everything else an error.  This serves the secondary
+    purpose of encouraging programmers not to accidentally give methods names
+    in the ``init`` family.
+
+    Note that a method with an ``init``-family selector which returns a
+    non-Objective-C type (e.g. ``void``) is perfectly well-formed; it simply
+    isn't in the ``init`` family.
+
+A program is ill-formed if a method's declarations, implementations, and
+overrides do not all have the same method family.
+
+.. _arc.family.attribute:
+
+Explicit method family control
+------------------------------
+
+A method may be annotated with the ``objc_method_family`` attribute to
+precisely control which method family it belongs to.  If a method in an
+``@implementation`` does not have this attribute, but there is a method
+declared in the corresponding ``@interface`` that does, then the attribute is
+copied to the declaration in the ``@implementation``.  The attribute is
+available outside of ARC, and may be tested for with the preprocessor query
+``__has_attribute(objc_method_family)``.
+
+The attribute is spelled
+``__attribute__((objc_method_family(`` *family* ``)))``.  If *family* is
+``none``, the method has no family, even if it would otherwise be considered to
+have one based on its selector and type.  Otherwise, *family* must be one of
+``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``, in which case the
+method is considered to belong to the corresponding family regardless of its
+selector.  It is an error if a method that is explicitly added to a family in
+this way does not meet the requirements of the family other than the selector
+naming convention.
+
+.. admonition:: Rationale
+
+  The rules codified in this document describe the standard conventions of
+  Objective-C.  However, as these conventions have not heretofore been enforced
+  by an unforgiving mechanical system, they are only imperfectly kept,
+  especially as they haven't always even been precisely defined.  While it is
+  possible to define low-level ownership semantics with attributes like
+  ``ns_returns_retained``, this attribute allows the user to communicate
+  semantic intent, which is of use both to ARC (which, e.g., treats calls to
+  ``init`` specially) and the static analyzer.
+
+.. _arc.family.semantics:
+
+Semantics of method families
+----------------------------
+
+A method's membership in a method family may imply non-standard semantics for
+its parameters and return type.
+
+Methods in the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families ---
+that is, methods in all the currently-defined families except ``init`` ---
+implicitly :ref:`return a retained object
+<arc.object.operands.retained-return-values>` as if they were annotated with
+the ``ns_returns_retained`` attribute.  This can be overridden by annotating
+the method with either of the ``ns_returns_autoreleased`` or
+``ns_returns_not_retained`` attributes.
+
+Properties also follow same naming rules as methods.  This means that those in
+the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families provide access
+to :ref:`retained objects <arc.object.operands.retained-return-values>`.  This
+can be overridden by annotating the property with ``ns_returns_not_retained``
+attribute.
+
+.. _arc.family.semantics.init:
+
+Semantics of ``init``
+^^^^^^^^^^^^^^^^^^^^^
+
+Methods in the ``init`` family implicitly :ref:`consume
+<arc.objects.operands.consumed>` their ``self`` parameter and :ref:`return a
+retained object <arc.object.operands.retained-return-values>`.  Neither of
+these properties can be altered through attributes.
+
+A call to an ``init`` method with a receiver that is either ``self`` (possibly
+parenthesized or casted) or ``super`` is called a :arc-term:`delegate init
+call`.  It is an error for a delegate init call to be made except from an
+``init`` method, and excluding blocks within such methods.
+
+As an exception to the :ref:`usual rule <arc.misc.self>`, the variable ``self``
+is mutable in an ``init`` method and has the usual semantics for a ``__strong``
+variable.  However, it is undefined behavior and the program is ill-formed, no
+diagnostic required, if an ``init`` method attempts to use the previous value
+of ``self`` after the completion of a delegate init call.  It is conventional,
+but not required, for an ``init`` method to return ``self``.
+
+It is undefined behavior for a program to cause two or more calls to ``init``
+methods on the same object, except that each ``init`` method invocation may
+perform at most one delegate init call.
+
+.. _arc.family.semantics.result_type:
+
+Related result types
+^^^^^^^^^^^^^^^^^^^^
+
+Certain methods are candidates to have :arc-term:`related result types`:
+
+* class methods in the ``alloc`` and ``new`` method families
+* instance methods in the ``init`` family
+* the instance method ``self``
+* outside of ARC, the instance methods ``retain`` and ``autorelease``
+
+If the formal result type of such a method is ``id`` or protocol-qualified
+``id``, or a type equal to the declaring class or a superclass, then it is said
+to have a related result type.  In this case, when invoked in an explicit
+message send, it is assumed to return a type related to the type of the
+receiver:
+
+* if it is a class method, and the receiver is a class name ``T``, the message
+  send expression has type ``T*``; otherwise
+* if it is an instance method, and the receiver has type ``T``, the message
+  send expression has type ``T``; otherwise
+* the message send expression has the normal result type of the method.
+
+This is a new rule of the Objective-C language and applies outside of ARC.
+
+.. admonition:: Rationale
+
+  ARC's automatic code emission is more prone than most code to signature
+  errors, i.e. errors where a call was emitted against one method signature,
+  but the implementing method has an incompatible signature.  Having more
+  precise type information helps drastically lower this risk, as well as
+  catching a number of latent bugs.
+
+.. _arc.optimization:
+
+Optimization
+============
+
+Within this section, the word :arc-term:`function` will be used to
+refer to any structured unit of code, be it a C function, an
+Objective-C method, or a block.
+
+This specification describes ARC as performing specific ``retain`` and
+``release`` operations on retainable object pointers at specific
+points during the execution of a program.  These operations make up a
+non-contiguous subsequence of the computation history of the program.
+The portion of this sequence for a particular retainable object
+pointer for which a specific function execution is directly
+responsible is the :arc-term:`formal local retain history` of the
+object pointer.  The corresponding actual sequence executed is the
+`dynamic local retain history`.
+
+However, under certain circumstances, ARC is permitted to re-order and
+eliminate operations in a manner which may alter the overall
+computation history beyond what is permitted by the general "as if"
+rule of C/C++ and the :ref:`restrictions <arc.objects.retains>` on
+the implementation of ``retain`` and ``release``.
+
+.. admonition:: Rationale
+
+  Specifically, ARC is sometimes permitted to optimize ``release``
+  operations in ways which might cause an object to be deallocated
+  before it would otherwise be.  Without this, it would be almost
+  impossible to eliminate any ``retain``/``release`` pairs.  For
+  example, consider the following code:
+
+  .. code-block:: objc
+
+    id x = _ivar;
+    [x foo];
+
+  If we were not permitted in any event to shorten the lifetime of the
+  object in ``x``, then we would not be able to eliminate this retain
+  and release unless we could prove that the message send could not
+  modify ``_ivar`` (or deallocate ``self``).  Since message sends are
+  opaque to the optimizer, this is not possible, and so ARC's hands
+  would be almost completely tied.
+
+ARC makes no guarantees about the execution of a computation history
+which contains undefined behavior.  In particular, ARC makes no
+guarantees in the presence of race conditions.
+
+ARC may assume that any retainable object pointers it receives or
+generates are instantaneously valid from that point until a point
+which, by the concurrency model of the host language, happens-after
+the generation of the pointer and happens-before a release of that
+object (possibly via an aliasing pointer or indirectly due to
+destruction of a different object).
+
+.. admonition:: Rationale
+
+  There is very little point in trying to guarantee correctness in the
+  presence of race conditions.  ARC does not have a stack-scanning
+  garbage collector, and guaranteeing the atomicity of every load and
+  store operation would be prohibitive and preclude a vast amount of
+  optimization.
+
+ARC may assume that non-ARC code engages in sensible balancing
+behavior and does not rely on exact or minimum retain count values
+except as guaranteed by ``__strong`` object invariants or +1 transfer
+conventions.  For example, if an object is provably double-retained
+and double-released, ARC may eliminate the inner retain and release;
+it does not need to guard against code which performs an unbalanced
+release followed by a "balancing" retain.
+
+.. _arc.optimization.liveness:
+
+Object liveness
+---------------
+
+ARC may not allow a retainable object ``X`` to be deallocated at a
+time ``T`` in a computation history if:
+
+* ``X`` is the value stored in a ``__strong`` object ``S`` with
+  :ref:`precise lifetime semantics <arc.optimization.precise>`, or
+
+* ``X`` is the value stored in a ``__strong`` object ``S`` with
+  imprecise lifetime semantics and, at some point after ``T`` but
+  before the next store to ``S``, the computation history features a
+  load from ``S`` and in some way depends on the value loaded, or
+
+* ``X`` is a value described as being released at the end of the
+  current full-expression and, at some point after ``T`` but before
+  the end of the full-expression, the computation history depends
+  on that value.
+
+.. admonition:: Rationale
+
+  The intent of the second rule is to say that objects held in normal
+  ``__strong`` local variables may be released as soon as the value in
+  the variable is no longer being used: either the variable stops
+  being used completely or a new value is stored in the variable.
+
+  The intent of the third rule is to say that return values may be
+  released after they've been used.
+
+A computation history depends on a pointer value ``P`` if it:
+
+* performs a pointer comparison with ``P``,
+* loads from ``P``,
+* stores to ``P``,
+* depends on a pointer value ``Q`` derived via pointer arithmetic
+  from ``P`` (including an instance-variable or field access), or
+* depends on a pointer value ``Q`` loaded from ``P``.
+
+Dependency applies only to values derived directly or indirectly from
+a particular expression result and does not occur merely because a
+separate pointer value dynamically aliases ``P``.  Furthermore, this
+dependency is not carried by values that are stored to objects.
+
+.. admonition:: Rationale
+
+  The restrictions on dependency are intended to make this analysis
+  feasible by an optimizer with only incomplete information about a
+  program.  Essentially, dependence is carried to "obvious" uses of a
+  pointer.  Merely passing a pointer argument to a function does not
+  itself cause dependence, but since generally the optimizer will not
+  be able to prove that the function doesn't depend on that parameter,
+  it will be forced to conservatively assume it does.
+
+  Dependency propagates to values loaded from a pointer because those
+  values might be invalidated by deallocating the object.  For
+  example, given the code ``__strong id x = p->ivar;``, ARC must not
+  move the release of ``p`` to between the load of ``p->ivar`` and the
+  retain of that value for storing into ``x``.
+
+  Dependency does not propagate through stores of dependent pointer
+  values because doing so would allow dependency to outlive the
+  full-expression which produced the original value.  For example, the
+  address of an instance variable could be written to some global
+  location and then freely accessed during the lifetime of the local,
+  or a function could return an inner pointer of an object and store
+  it to a local.  These cases would be potentially impossible to
+  reason about and so would basically prevent any optimizations based
+  on imprecise lifetime.  There are also uncommon enough to make it
+  reasonable to require the precise-lifetime annotation if someone
+  really wants to rely on them.
+
+  Dependency does propagate through return values of pointer type.
+  The compelling source of need for this rule is a property accessor
+  which returns an un-autoreleased result; the calling function must
+  have the chance to operate on the value, e.g. to retain it, before
+  ARC releases the original pointer.  Note again, however, that
+  dependence does not survive a store, so ARC does not guarantee the
+  continued validity of the return value past the end of the
+  full-expression.
+
+.. _arc.optimization.object_lifetime:
+
+No object lifetime extension
+----------------------------
+
+If, in the formal computation history of the program, an object ``X``
+has been deallocated by the time of an observable side-effect, then
+ARC must cause ``X`` to be deallocated by no later than the occurrence
+of that side-effect, except as influenced by the re-ordering of the
+destruction of objects.
+
+.. admonition:: Rationale
+
+  This rule is intended to prohibit ARC from observably extending the
+  lifetime of a retainable object, other than as specified in this
+  document.  Together with the rule limiting the transformation of
+  releases, this rule requires ARC to eliminate retains and release
+  only in pairs.
+
+  ARC's power to reorder the destruction of objects is critical to its
+  ability to do any optimization, for essentially the same reason that
+  it must retain the power to decrease the lifetime of an object.
+  Unfortunately, while it's generally poor style for the destruction
+  of objects to have arbitrary side-effects, it's certainly possible.
+  Hence the caveat.
+
+.. _arc.optimization.precise:
+
+Precise lifetime semantics
+--------------------------
+
+In general, ARC maintains an invariant that a retainable object pointer held in
+a ``__strong`` object will be retained for the full formal lifetime of the
+object.  Objects subject to this invariant have :arc-term:`precise lifetime
+semantics`.
+
+By default, local variables of automatic storage duration do not have precise
+lifetime semantics.  Such objects are simply strong references which hold
+values of retainable object pointer type, and these values are still fully
+subject to the optimizations on values under local control.
+
+.. admonition:: Rationale
+
+  Applying these precise-lifetime semantics strictly would be prohibitive.
+  Many useful optimizations that might theoretically decrease the lifetime of
+  an object would be rendered impossible.  Essentially, it promises too much.
+
+A local variable of retainable object owner type and automatic storage duration
+may be annotated with the ``objc_precise_lifetime`` attribute to indicate that
+it should be considered to be an object with precise lifetime semantics.
+
+.. admonition:: Rationale
+
+  Nonetheless, it is sometimes useful to be able to force an object to be
+  released at a precise time, even if that object does not appear to be used.
+  This is likely to be uncommon enough that the syntactic weight of explicitly
+  requesting these semantics will not be burdensome, and may even make the code
+  clearer.
+
+.. _arc.misc:
+
+Miscellaneous
+=============
+
+.. _arc.misc.special_methods:
+
+Special methods
+---------------
+
+.. _arc.misc.special_methods.retain:
+
+Memory management methods
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A program is ill-formed if it contains a method definition, message send, or
+``@selector`` expression for any of the following selectors:
+
+* ``autorelease``
+* ``release``
+* ``retain``
+* ``retainCount``
+
+.. admonition:: Rationale
+
+  ``retainCount`` is banned because ARC robs it of consistent semantics.  The
+  others were banned after weighing three options for how to deal with message
+  sends:
+
+  **Honoring** them would work out very poorly if a programmer naively or
+  accidentally tried to incorporate code written for manual retain/release code
+  into an ARC program.  At best, such code would do twice as much work as
+  necessary; quite frequently, however, ARC and the explicit code would both
+  try to balance the same retain, leading to crashes.  The cost is losing the
+  ability to perform "unrooted" retains, i.e. retains not logically
+  corresponding to a strong reference in the object graph.
+
+  **Ignoring** them would badly violate user expectations about their code.
+  While it *would* make it easier to develop code simultaneously for ARC and
+  non-ARC, there is very little reason to do so except for certain library
+  developers.  ARC and non-ARC translation units share an execution model and
+  can seamlessly interoperate.  Within a translation unit, a developer who
+  faithfully maintains their code in non-ARC mode is suffering all the
+  restrictions of ARC for zero benefit, while a developer who isn't testing the
+  non-ARC mode is likely to be unpleasantly surprised if they try to go back to
+  it.
+
+  **Banning** them has the disadvantage of making it very awkward to migrate
+  existing code to ARC.  The best answer to that, given a number of other
+  changes and restrictions in ARC, is to provide a specialized tool to assist
+  users in that migration.
+
+  Implementing these methods was banned because they are too integral to the
+  semantics of ARC; many tricks which worked tolerably under manual reference
+  counting will misbehave if ARC performs an ephemeral extra retain or two.  If
+  absolutely required, it is still possible to implement them in non-ARC code,
+  for example in a category; the implementations must obey the :ref:`semantics
+  <arc.objects.retains>` laid out elsewhere in this document.
+
+.. _arc.misc.special_methods.dealloc:
+
+``dealloc``
+^^^^^^^^^^^
+
+A program is ill-formed if it contains a message send or ``@selector``
+expression for the selector ``dealloc``.
+
+.. admonition:: Rationale
+
+  There are no legitimate reasons to call ``dealloc`` directly.
+
+A class may provide a method definition for an instance method named
+``dealloc``.  This method will be called after the final ``release`` of the
+object but before it is deallocated or any of its instance variables are
+destroyed.  The superclass's implementation of ``dealloc`` will be called
+automatically when the method returns.
+
+.. admonition:: Rationale
+
+  Even though ARC destroys instance variables automatically, there are still
+  legitimate reasons to write a ``dealloc`` method, such as freeing
+  non-retainable resources.  Failing to call ``[super dealloc]`` in such a
+  method is nearly always a bug.  Sometimes, the object is simply trying to
+  prevent itself from being destroyed, but ``dealloc`` is really far too late
+  for the object to be raising such objections.  Somewhat more legitimately, an
+  object may have been pool-allocated and should not be deallocated with
+  ``free``; for now, this can only be supported with a ``dealloc``
+  implementation outside of ARC.  Such an implementation must be very careful
+  to do all the other work that ``NSObject``'s ``dealloc`` would, which is
+  outside the scope of this document to describe.
+
+The instance variables for an ARC-compiled class will be destroyed at some
+point after control enters the ``dealloc`` method for the root class of the
+class.  The ordering of the destruction of instance variables is unspecified,
+both within a single class and between subclasses and superclasses.
+
+.. admonition:: Rationale
+
+  The traditional, non-ARC pattern for destroying instance variables is to
+  destroy them immediately before calling ``[super dealloc]``.  Unfortunately,
+  message sends from the superclass are quite capable of reaching methods in
+  the subclass, and those methods may well read or write to those instance
+  variables.  Making such message sends from dealloc is generally discouraged,
+  since the subclass may well rely on other invariants that were broken during
+  ``dealloc``, but it's not so inescapably dangerous that we felt comfortable
+  calling it undefined behavior.  Therefore we chose to delay destroying the
+  instance variables to a point at which message sends are clearly disallowed:
+  the point at which the root class's deallocation routines take over.
+
+  In most code, the difference is not observable.  It can, however, be observed
+  if an instance variable holds a strong reference to an object whose
+  deallocation will trigger a side-effect which must be carefully ordered with
+  respect to the destruction of the super class.  Such code violates the design
+  principle that semantically important behavior should be explicit.  A simple
+  fix is to clear the instance variable manually during ``dealloc``; a more
+  holistic solution is to move semantically important side-effects out of
+  ``dealloc`` and into a separate teardown phase which can rely on working with
+  well-formed objects.
+
+.. _arc.misc.autoreleasepool:
+
+``@autoreleasepool``
+--------------------
+
+To simplify the use of autorelease pools, and to bring them under the control
+of the compiler, a new kind of statement is available in Objective-C.  It is
+written ``@autoreleasepool`` followed by a *compound-statement*, i.e.  by a new
+scope delimited by curly braces.  Upon entry to this block, the current state
+of the autorelease pool is captured.  When the block is exited normally,
+whether by fallthrough or directed control flow (such as ``return`` or
+``break``), the autorelease pool is restored to the saved state, releasing all
+the objects in it.  When the block is exited with an exception, the pool is not
+drained.
+
+``@autoreleasepool`` may be used in non-ARC translation units, with equivalent
+semantics.
+
+A program is ill-formed if it refers to the ``NSAutoreleasePool`` class.
+
+.. admonition:: Rationale
+
+  Autorelease pools are clearly important for the compiler to reason about, but
+  it is far too much to expect the compiler to accurately reason about control
+  dependencies between two calls.  It is also very easy to accidentally forget
+  to drain an autorelease pool when using the manual API, and this can
+  significantly inflate the process's high-water-mark.  The introduction of a
+  new scope is unfortunate but basically required for sane interaction with the
+  rest of the language.  Not draining the pool during an unwind is apparently
+  required by the Objective-C exceptions implementation.
+
+.. _arc.misc.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
+
+  void objc_storeStrong(id *object, id value) {
+    id oldValue = *object;
+    value = [value retain];
+    *object = value;
+    [oldValue release];
+  }
+
+.. [*] This does not imply that a ``__strong`` object of block type is an
+   invalid argument to this function. Rather it implies that an ``objc_retain``
+   and not an ``objc_retainBlock`` operation will be emitted if the argument is
+   a block.
+
+.. _arc.runtime.objc_storeWeak:
+
+``id objc_storeWeak(id *object, id value);``
+--------------------------------------------
+
+*Precondition:* ``object`` is a valid pointer which either contains a null
+pointer or has been registered as a ``__weak`` object.  ``value`` is null or a
+pointer to a valid object.
+
+If ``value`` is a null pointer or the object to which it points has begun
+deallocation, ``object`` is assigned null and unregistered as a ``__weak``
+object.  Otherwise, ``object`` is registered as a ``__weak`` object or has its
+registration updated to point to ``value``.
+
+Returns the value of ``object`` after the call.
+

Added: www-releases/trunk/7.0.0/tools/clang/docs/_sources/Block-ABI-Apple.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/Block-ABI-Apple.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/Block-ABI-Apple.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/Block-ABI-Apple.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,943 @@
+==================================
+Block Implementation Specification
+==================================
+
+.. contents::
+   :local:
+
+History
+=======
+
+* 2008/7/14 - created.
+* 2008/8/21 - revised, C++.
+* 2008/9/24 - add ``NULL`` ``isa`` field to ``__block`` storage.
+* 2008/10/1 - revise block layout to use a ``static`` descriptor structure.
+* 2008/10/6 - revise block layout to use an unsigned long int flags.
+* 2008/10/28 - specify use of ``_Block_object_assign`` and
+  ``_Block_object_dispose`` for all "Object" types in helper functions.
+* 2008/10/30 - revise new layout to have invoke function in same place.
+* 2008/10/30 - add ``__weak`` support.
+* 2010/3/16 - rev for stret return, signature field.
+* 2010/4/6 - improved wording.
+* 2013/1/6 - improved wording and converted to rst.
+
+This document describes the Apple ABI implementation specification of Blocks.
+
+The first shipping version of this ABI is found in Mac OS X 10.6, and shall be
+referred to as 10.6.ABI. As of 2010/3/16, the following describes the ABI
+contract with the runtime and the compiler, and, as necessary, will be referred
+to as ABI.2010.3.16.
+
+Since the Apple ABI references symbols from other elements of the system, any
+attempt to use this ABI on systems prior to SnowLeopard is undefined.
+
+High Level
+==========
+
+The ABI of ``Blocks`` consist of their layout and the runtime functions required
+by the compiler.  A ``Block`` consists of a structure of the following form:
+
+.. code-block:: c
+
+    struct Block_literal_1 {
+        void *isa; // initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock
+        int flags;
+        int reserved; 
+        void (*invoke)(void *, ...);
+        struct Block_descriptor_1 {
+        unsigned long int reserved;         // NULL
+            unsigned long int size;         // sizeof(struct Block_literal_1)
+            // optional helper functions
+            void (*copy_helper)(void *dst, void *src);     // IFF (1<<25)
+            void (*dispose_helper)(void *src);             // IFF (1<<25)
+            // required ABI.2010.3.16
+            const char *signature;                         // IFF (1<<30)
+        } *descriptor;
+        // imported variables
+    };
+
+The following flags bits are in use thusly for a possible ABI.2010.3.16:
+
+.. code-block:: c
+
+    enum {
+        // Set to true on blocks that have captures (and thus are not true
+        // global blocks) but are known not to escape for various other
+        // reasons. For backward compatiblity with old runtimes, whenever
+        // BLOCK_IS_NOESCAPE is set, BLOCK_IS_GLOBAL is set too. Copying a
+        // non-escaping block returns the original block and releasing such a
+        // block is a no-op, which is exactly how global blocks are handled.
+        BLOCK_IS_NOESCAPE      =  (1 << 23),
+
+        BLOCK_HAS_COPY_DISPOSE =  (1 << 25),
+        BLOCK_HAS_CTOR =          (1 << 26), // helpers have C++ code
+        BLOCK_IS_GLOBAL =         (1 << 28),
+        BLOCK_HAS_STRET =         (1 << 29), // IFF BLOCK_HAS_SIGNATURE
+        BLOCK_HAS_SIGNATURE =     (1 << 30), 
+    };
+
+In 10.6.ABI the (1<<29) was usually set and was always ignored by the runtime -
+it had been a transitional marker that did not get deleted after the
+transition. This bit is now paired with (1<<30), and represented as the pair
+(3<<30), for the following combinations of valid bit settings, and their
+meanings:
+
+.. code-block:: c
+
+    switch (flags & (3<<29)) {
+      case (0<<29):      10.6.ABI, no signature field available
+      case (1<<29):      10.6.ABI, no signature field available
+      case (2<<29): ABI.2010.3.16, regular calling convention, presence of signature field
+      case (3<<29): ABI.2010.3.16, stret calling convention, presence of signature field,
+    }
+
+The signature field is not always populated.
+
+The following discussions are presented as 10.6.ABI otherwise.
+
+``Block`` literals may occur within functions where the structure is created in
+stack local memory.  They may also appear as initialization expressions for
+``Block`` variables of global or ``static`` local variables.
+
+When a ``Block`` literal expression is evaluated the stack based structure is
+initialized as follows:
+
+1. A ``static`` descriptor structure is declared and initialized as follows:
+  
+  a. The ``invoke`` function pointer is set to a function that takes the
+  ``Block`` structure as its first argument and the rest of the arguments (if
+  any) to the ``Block`` and executes the ``Block`` compound statement.
+  
+  b. The ``size`` field is set to the size of the following ``Block`` literal
+  structure.
+  
+  c. The ``copy_helper`` and ``dispose_helper`` function pointers are set to
+  respective helper functions if they are required by the ``Block`` literal.
+
+2. A stack (or global) ``Block`` literal data structure is created and
+   initialized as follows:
+   
+   a. The ``isa`` field is set to the address of the external
+   ``_NSConcreteStackBlock``, which is a block of uninitialized memory supplied
+   in ``libSystem``, or ``_NSConcreteGlobalBlock`` if this is a static or file
+   level ``Block`` literal.
+   
+   b. The ``flags`` field is set to zero unless there are variables imported
+   into the ``Block`` that need helper functions for program level
+   ``Block_copy()`` and ``Block_release()`` operations, in which case the
+   (1<<25) flags bit is set.
+
+As an example, the ``Block`` literal expression:
+
+.. code-block:: c
+
+    ^ { printf("hello world\n"); }
+
+would cause the following to be created on a 32-bit system:
+
+.. code-block:: c
+
+    struct __block_literal_1 {
+        void *isa;
+        int flags;
+        int reserved; 
+        void (*invoke)(struct __block_literal_1 *);
+        struct __block_descriptor_1 *descriptor;
+    };
+    
+    void __block_invoke_1(struct __block_literal_1 *_block) {
+        printf("hello world\n");
+    }
+    
+    static struct __block_descriptor_1 {
+        unsigned long int reserved;
+        unsigned long int Block_size;
+    } __block_descriptor_1 = { 0, sizeof(struct __block_literal_1), __block_invoke_1 };
+
+and where the ``Block`` literal itself appears:
+
+.. code-block:: c
+
+    struct __block_literal_1 _block_literal = {
+         &_NSConcreteStackBlock,
+         (1<<29), <uninitialized>,
+         __block_invoke_1,
+         &__block_descriptor_1
+    };
+
+A ``Block`` imports other ``Block`` references, ``const`` copies of other
+variables, and variables marked ``__block``.  In Objective-C, variables may
+additionally be objects.
+
+When a ``Block`` literal expression is used as the initial value of a global
+or ``static`` local variable, it is initialized as follows:
+
+.. code-block:: c
+
+    struct __block_literal_1 __block_literal_1 = {
+          &_NSConcreteGlobalBlock,
+          (1<<28)|(1<<29), <uninitialized>,
+          __block_invoke_1,
+          &__block_descriptor_1
+    };
+
+that is, a different address is provided as the first value and a particular
+(1<<28) bit is set in the ``flags`` field, and otherwise it is the same as for
+stack based ``Block`` literals.  This is an optimization that can be used for
+any ``Block`` literal that imports no ``const`` or ``__block`` storage
+variables.
+
+Imported Variables
+==================
+
+Variables of ``auto`` storage class are imported as ``const`` copies.  Variables
+of ``__block`` storage class are imported as a pointer to an enclosing data
+structure.  Global variables are simply referenced and not considered as
+imported.
+
+Imported ``const`` copy variables
+---------------------------------
+
+Automatic storage variables not marked with ``__block`` are imported as
+``const`` copies.
+
+The simplest example is that of importing a variable of type ``int``:
+
+.. code-block:: c
+
+    int x = 10;
+    void (^vv)(void) = ^{ printf("x is %d\n", x); }
+    x = 11;
+    vv();
+
+which would be compiled to:
+
+.. code-block:: c
+    
+    struct __block_literal_2 {
+        void *isa;
+        int flags;
+        int reserved; 
+        void (*invoke)(struct __block_literal_2 *);
+        struct __block_descriptor_2 *descriptor;
+        const int x;
+    };
+    
+    void __block_invoke_2(struct __block_literal_2 *_block) {
+        printf("x is %d\n", _block->x);
+    }
+    
+    static struct __block_descriptor_2 {
+        unsigned long int reserved;
+        unsigned long int Block_size;
+    } __block_descriptor_2 = { 0, sizeof(struct __block_literal_2) };
+
+and:
+
+.. code-block:: c
+
+    struct __block_literal_2 __block_literal_2 = {
+          &_NSConcreteStackBlock,
+          (1<<29), <uninitialized>,
+          __block_invoke_2,
+          &__block_descriptor_2,
+          x
+     };
+
+In summary, scalars, structures, unions, and function pointers are generally
+imported as ``const`` copies with no need for helper functions.
+
+Imported ``const`` copy of ``Block`` reference
+----------------------------------------------
+
+The first case where copy and dispose helper functions are required is for the
+case of when a ``Block`` itself is imported.  In this case both a
+``copy_helper`` function and a ``dispose_helper`` function are needed.  The
+``copy_helper`` function is passed both the existing stack based pointer and the
+pointer to the new heap version and should call back into the runtime to
+actually do the copy operation on the imported fields within the ``Block``. The
+runtime functions are all described in :ref:`RuntimeHelperFunctions`.
+
+A quick example:
+
+.. code-block:: c
+
+    void (^existingBlock)(void) = ...;
+    void (^vv)(void) = ^{ existingBlock(); }
+    vv();
+    
+    struct __block_literal_3 {
+       ...; // existing block
+    };
+    
+    struct __block_literal_4 {
+        void *isa;
+        int flags;
+        int reserved; 
+        void (*invoke)(struct __block_literal_4 *);
+        struct __block_literal_3 *const existingBlock;
+    };
+    
+    void __block_invoke_4(struct __block_literal_2 *_block) {
+       __block->existingBlock->invoke(__block->existingBlock);
+    }
+    
+    void __block_copy_4(struct __block_literal_4 *dst, struct __block_literal_4 *src) {
+         //_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0);
+         _Block_object_assign(&dst->existingBlock, src->existingBlock, BLOCK_FIELD_IS_BLOCK);
+    }
+    
+    void __block_dispose_4(struct __block_literal_4 *src) {
+         // was _Block_destroy
+         _Block_object_dispose(src->existingBlock, BLOCK_FIELD_IS_BLOCK);
+    }
+    
+    static struct __block_descriptor_4 {
+        unsigned long int reserved;
+        unsigned long int Block_size;
+        void (*copy_helper)(struct __block_literal_4 *dst, struct __block_literal_4 *src);
+        void (*dispose_helper)(struct __block_literal_4 *);
+    } __block_descriptor_4 = {
+        0,
+        sizeof(struct __block_literal_4),
+        __block_copy_4,
+        __block_dispose_4,
+    };
+
+and where said ``Block`` is used:
+
+.. code-block:: c
+
+    struct __block_literal_4 _block_literal = {
+          &_NSConcreteStackBlock,
+          (1<<25)|(1<<29), <uninitialized>
+          __block_invoke_4,
+          & __block_descriptor_4
+          existingBlock,
+    };
+
+Importing ``__attribute__((NSObject))`` variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GCC introduces ``__attribute__((NSObject))`` on structure pointers to mean "this
+is an object".  This is useful because many low level data structures are
+declared as opaque structure pointers, e.g. ``CFStringRef``, ``CFArrayRef``,
+etc.  When used from C, however, these are still really objects and are the
+second case where that requires copy and dispose helper functions to be
+generated.  The copy helper functions generated by the compiler should use the
+``_Block_object_assign`` runtime helper function and in the dispose helper the
+``_Block_object_dispose`` runtime helper function should be called.
+
+For example, ``Block`` foo in the following:
+
+.. code-block:: c
+
+    struct Opaque *__attribute__((NSObject)) objectPointer = ...;
+    ...
+    void (^foo)(void) = ^{  CFPrint(objectPointer); };
+
+would have the following helper functions generated:
+
+.. code-block:: c
+
+    void __block_copy_foo(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+         _Block_object_assign(&dst->objectPointer, src-> objectPointer, BLOCK_FIELD_IS_OBJECT);
+    }
+    
+    void __block_dispose_foo(struct __block_literal_5 *src) {
+         _Block_object_dispose(src->objectPointer, BLOCK_FIELD_IS_OBJECT);
+    }
+
+Imported ``__block`` marked variables
+-------------------------------------
+
+Layout of ``__block`` marked variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The compiler must embed variables that are marked ``__block`` in a specialized
+structure of the form:
+
+.. code-block:: c
+
+    struct _block_byref_foo {
+        void *isa;
+        struct Block_byref *forwarding;
+        int flags;   //refcount;
+        int size;
+        typeof(marked_variable) marked_variable;
+    };
+
+Variables of certain types require helper functions for when ``Block_copy()``
+and ``Block_release()`` are performed upon a referencing ``Block``.  At the "C"
+level only variables that are of type ``Block`` or ones that have
+``__attribute__((NSObject))`` marked require helper functions.  In Objective-C
+objects require helper functions and in C++ stack based objects require helper
+functions. Variables that require helper functions use the form:
+
+.. code-block:: c
+
+    struct _block_byref_foo {
+        void *isa;
+        struct _block_byref_foo *forwarding;
+        int flags;   //refcount;
+        int size;
+        // helper functions called via Block_copy() and Block_release()
+        void (*byref_keep)(void  *dst, void *src);
+        void (*byref_dispose)(void *);
+        typeof(marked_variable) marked_variable;
+    };
+
+The structure is initialized such that:
+
+    a. The ``forwarding`` pointer is set to the beginning of its enclosing
+    structure.
+    
+    b. The ``size`` field is initialized to the total size of the enclosing
+    structure.    
+    
+    c. The ``flags`` field is set to either 0 if no helper functions are needed
+    or (1<<25) if they are.    
+    
+    d. The helper functions are initialized (if present).    
+    
+    e. The variable itself is set to its initial value.    
+    
+    f. The ``isa`` field is set to ``NULL``.
+
+Access to ``__block`` variables from within its lexical scope
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to "move" the variable to the heap upon a ``copy_helper`` operation the
+compiler must rewrite access to such a variable to be indirect through the
+structures ``forwarding`` pointer.  For example:
+
+.. code-block:: c
+
+    int __block i = 10;
+    i = 11;
+
+would be rewritten to be:
+
+.. code-block:: c
+
+    struct _block_byref_i {
+      void *isa;
+      struct _block_byref_i *forwarding;
+      int flags;   //refcount;
+      int size;
+      int captured_i;
+    } i = { NULL, &i, 0, sizeof(struct _block_byref_i), 10 };
+    
+    i.forwarding->captured_i = 11;
+
+In the case of a ``Block`` reference variable being marked ``__block`` the
+helper code generated must use the ``_Block_object_assign`` and
+``_Block_object_dispose`` routines supplied by the runtime to make the
+copies. For example:
+
+.. code-block:: c
+
+    __block void (voidBlock)(void) = blockA;
+    voidBlock = blockB;
+
+would translate into:
+
+.. code-block:: c
+
+    struct _block_byref_voidBlock {
+        void *isa;
+        struct _block_byref_voidBlock *forwarding;
+        int flags;   //refcount;
+        int size;
+        void (*byref_keep)(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src);
+        void (*byref_dispose)(struct _block_byref_voidBlock *);
+        void (^captured_voidBlock)(void);
+    };
+    
+    void _block_byref_keep_helper(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) {
+        //_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0);
+        _Block_object_assign(&dst->captured_voidBlock, src->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER);
+    }
+    
+    void _block_byref_dispose_helper(struct _block_byref_voidBlock *param) {
+        //_Block_destroy(param->captured_voidBlock, 0);
+        _Block_object_dispose(param->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER)}
+
+and:
+
+.. code-block:: c
+
+    struct _block_byref_voidBlock voidBlock = {( .forwarding=&voidBlock, .flags=(1<<25), .size=sizeof(struct _block_byref_voidBlock *),
+        .byref_keep=_block_byref_keep_helper, .byref_dispose=_block_byref_dispose_helper,
+        .captured_voidBlock=blockA )};
+    
+    voidBlock.forwarding->captured_voidBlock = blockB;
+
+Importing ``__block`` variables into ``Blocks``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``Block`` that uses a ``__block`` variable in its compound statement body must
+import the variable and emit ``copy_helper`` and ``dispose_helper`` helper
+functions that, in turn, call back into the runtime to actually copy or release
+the ``byref`` data block using the functions ``_Block_object_assign`` and
+``_Block_object_dispose``.
+
+For example:
+
+.. code-block:: c
+
+    int __block i = 2;
+    functioncall(^{ i = 10; });
+
+would translate to:
+
+.. code-block:: c
+
+    struct _block_byref_i {
+        void *isa;  // set to NULL
+        struct _block_byref_voidBlock *forwarding;
+        int flags;   //refcount;
+        int size;
+        void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src);
+        void (*byref_dispose)(struct _block_byref_i *);
+        int captured_i;
+    };
+    
+    
+    struct __block_literal_5 {
+        void *isa;
+        int flags;
+        int reserved; 
+        void (*invoke)(struct __block_literal_5 *);
+        struct __block_descriptor_5 *descriptor;
+        struct _block_byref_i *i_holder;
+    };
+    
+    void __block_invoke_5(struct __block_literal_5 *_block) {
+       _block->forwarding->captured_i = 10;
+    }
+    
+    void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+         //_Block_byref_assign_copy(&dst->captured_i, src->captured_i);
+         _Block_object_assign(&dst->captured_i, src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER);
+    }
+    
+    void __block_dispose_5(struct __block_literal_5 *src) {
+         //_Block_byref_release(src->captured_i);
+         _Block_object_dispose(src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER);
+    }
+    
+    static struct __block_descriptor_5 {
+        unsigned long int reserved;
+        unsigned long int Block_size;
+        void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src);
+        void (*dispose_helper)(struct __block_literal_5 *);
+    } __block_descriptor_5 = { 0, sizeof(struct __block_literal_5) __block_copy_5, __block_dispose_5 };
+
+and:
+
+.. code-block:: c
+
+    struct _block_byref_i i = {( .isa=NULL, .forwarding=&i, .flags=0, .size=sizeof(struct _block_byref_i), .captured_i=2 )};
+    struct __block_literal_5 _block_literal = {
+          &_NSConcreteStackBlock,
+          (1<<25)|(1<<29), <uninitialized>,
+          __block_invoke_5,
+          &__block_descriptor_5,
+          &i,
+    };
+
+Importing ``__attribute__((NSObject))`` ``__block`` variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``__block`` variable that is also marked ``__attribute__((NSObject))`` should
+have ``byref_keep`` and ``byref_dispose`` helper functions that use
+``_Block_object_assign`` and ``_Block_object_dispose``.
+
+``__block`` escapes
+^^^^^^^^^^^^^^^^^^^
+
+Because ``Blocks`` referencing ``__block`` variables may have ``Block_copy()``
+performed upon them the underlying storage for the variables may move to the
+heap.  In Objective-C Garbage Collection Only compilation environments the heap
+used is the garbage collected one and no further action is required.  Otherwise
+the compiler must issue a call to potentially release any heap storage for
+``__block`` variables at all escapes or terminations of their scope.  The call
+should be:
+
+.. code-block:: c
+
+    _Block_object_dispose(&_block_byref_foo, BLOCK_FIELD_IS_BYREF);
+
+Nesting
+^^^^^^^
+
+``Blocks`` may contain ``Block`` literal expressions.  Any variables used within
+inner blocks are imported into all enclosing ``Block`` scopes even if the
+variables are not used. This includes ``const`` imports as well as ``__block``
+variables.
+
+Objective C Extensions to ``Blocks``
+====================================
+
+Importing Objects
+-----------------
+
+Objects should be treated as ``__attribute__((NSObject))`` variables; all
+``copy_helper``, ``dispose_helper``, ``byref_keep``, and ``byref_dispose``
+helper functions should use ``_Block_object_assign`` and
+``_Block_object_dispose``.  There should be no code generated that uses
+``*-retain`` or ``*-release`` methods.
+
+``Blocks`` as Objects
+---------------------
+
+The compiler will treat ``Blocks`` as objects when synthesizing property setters
+and getters, will characterize them as objects when generating garbage
+collection strong and weak layout information in the same manner as objects, and
+will issue strong and weak write-barrier assignments in the same manner as
+objects.
+
+``__weak __block`` Support
+--------------------------
+
+Objective-C (and Objective-C++) support the ``__weak`` attribute on ``__block``
+variables.  Under normal circumstances the compiler uses the Objective-C runtime
+helper support functions ``objc_assign_weak`` and ``objc_read_weak``.  Both
+should continue to be used for all reads and writes of ``__weak __block``
+variables:
+
+.. code-block:: c
+
+    objc_read_weak(&block->byref_i->forwarding->i)
+
+The ``__weak`` variable is stored in a ``_block_byref_foo`` structure and the
+``Block`` has copy and dispose helpers for this structure that call:
+
+.. code-block:: c
+
+    _Block_object_assign(&dest->_block_byref_i, src-> _block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF);
+
+and:
+
+.. code-block:: c
+
+    _Block_object_dispose(src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF);
+
+In turn, the ``block_byref`` copy support helpers distinguish between whether
+the ``__block`` variable is a ``Block`` or not and should either call:
+
+.. code-block:: c
+
+    _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_OBJECT | BLOCK_BYREF_CALLER);
+
+for something declared as an object or:
+
+.. code-block:: c
+
+    _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER);
+
+for something declared as a ``Block``.
+
+A full example follows:
+
+.. code-block:: c
+
+    __block __weak id obj = <initialization expression>;
+    functioncall(^{ [obj somemessage]; });
+
+would translate to:
+
+.. code-block:: c
+
+    struct _block_byref_obj {
+        void *isa;  // uninitialized
+        struct _block_byref_obj *forwarding;
+        int flags;   //refcount;
+        int size;
+        void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src);
+        void (*byref_dispose)(struct _block_byref_i *);
+        id captured_obj;
+    };
+    
+    void _block_byref_obj_keep(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) {
+        //_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0);
+        _Block_object_assign(&dst->captured_obj, src->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER);
+    }
+    
+    void _block_byref_obj_dispose(struct _block_byref_voidBlock *param) {
+        //_Block_destroy(param->captured_obj, 0);
+        _Block_object_dispose(param->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER);
+    };
+
+for the block ``byref`` part and:
+
+.. code-block:: c
+
+    struct __block_literal_5 {
+        void *isa;
+        int flags;
+        int reserved; 
+        void (*invoke)(struct __block_literal_5 *);
+        struct __block_descriptor_5 *descriptor;
+        struct _block_byref_obj *byref_obj;
+    };
+    
+    void __block_invoke_5(struct __block_literal_5 *_block) {
+       [objc_read_weak(&_block->byref_obj->forwarding->captured_obj) somemessage];
+    }
+    
+    void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) {
+         //_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj);
+         _Block_object_assign(&dst->byref_obj, src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK);
+    }
+    
+    void __block_dispose_5(struct __block_literal_5 *src) {
+         //_Block_byref_release(src->byref_obj);
+         _Block_object_dispose(src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK);
+    }
+    
+    static struct __block_descriptor_5 {
+        unsigned long int reserved;
+        unsigned long int Block_size;
+        void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src);
+        void (*dispose_helper)(struct __block_literal_5 *);
+    } __block_descriptor_5 = { 0, sizeof(struct __block_literal_5), __block_copy_5, __block_dispose_5 };
+
+and within the compound statement:
+
+.. code-block:: c
+
+    truct _block_byref_obj obj = {( .forwarding=&obj, .flags=(1<<25), .size=sizeof(struct _block_byref_obj),
+                     .byref_keep=_block_byref_obj_keep, .byref_dispose=_block_byref_obj_dispose,
+                     .captured_obj = <initialization expression> )};
+    
+    truct __block_literal_5 _block_literal = {
+         &_NSConcreteStackBlock,
+         (1<<25)|(1<<29), <uninitialized>,
+         __block_invoke_5,
+         &__block_descriptor_5,
+         &obj,        // a reference to the on-stack structure containing "captured_obj"
+    };
+    
+    
+    functioncall(_block_literal->invoke(&_block_literal));
+
+C++ Support
+===========
+
+Within a block stack based C++ objects are copied into ``const`` copies using
+the copy constructor.  It is an error if a stack based C++ object is used within
+a block if it does not have a copy constructor.  In addition both copy and
+destroy helper routines must be synthesized for the block to support the
+``Block_copy()`` operation, and the flags work marked with the (1<<26) bit in
+addition to the (1<<25) bit.  The copy helper should call the constructor using
+appropriate offsets of the variable within the supplied stack based block source
+and heap based destination for all ``const`` constructed copies, and similarly
+should call the destructor in the destroy routine.
+
+As an example, suppose a C++ class ``FOO`` existed with a copy constructor.
+Within a code block a stack version of a ``FOO`` object is declared and used
+within a ``Block`` literal expression:
+
+.. code-block:: c++
+
+    {
+        FOO foo;
+        void (^block)(void) = ^{ printf("%d\n", foo.value()); };
+    }
+
+The compiler would synthesize:
+
+.. code-block:: c++
+
+    struct __block_literal_10 {
+        void *isa;
+        int flags;
+        int reserved; 
+        void (*invoke)(struct __block_literal_10 *);
+        struct __block_descriptor_10 *descriptor;
+        const FOO foo;
+    };
+    
+    void __block_invoke_10(struct __block_literal_10 *_block) {
+       printf("%d\n", _block->foo.value());
+    }
+    
+    void __block_literal_10(struct __block_literal_10 *dst, struct __block_literal_10 *src) {
+         FOO_ctor(&dst->foo, &src->foo);
+    }
+    
+    void __block_dispose_10(struct __block_literal_10 *src) {
+         FOO_dtor(&src->foo);
+    }
+    
+    static struct __block_descriptor_10 {
+        unsigned long int reserved;
+        unsigned long int Block_size;
+        void (*copy_helper)(struct __block_literal_10 *dst, struct __block_literal_10 *src);
+        void (*dispose_helper)(struct __block_literal_10 *);
+    } __block_descriptor_10 = { 0, sizeof(struct __block_literal_10), __block_copy_10, __block_dispose_10 };
+
+and the code would be:
+
+.. code-block:: c++
+
+    {
+      FOO foo;
+      comp_ctor(&foo); // default constructor
+      struct __block_literal_10 _block_literal = {
+        &_NSConcreteStackBlock,
+        (1<<25)|(1<<26)|(1<<29), <uninitialized>,
+        __block_invoke_10,
+        &__block_descriptor_10,
+       };
+       comp_ctor(&_block_literal->foo, &foo);  // const copy into stack version
+       struct __block_literal_10 &block = &_block_literal;  // assign literal to block variable
+       block->invoke(block);    // invoke block
+       comp_dtor(&_block_literal->foo); // destroy stack version of const block copy
+       comp_dtor(&foo); // destroy original version
+    }
+
+
+C++ objects stored in ``__block`` storage start out on the stack in a
+``block_byref`` data structure as do other variables.  Such objects (if not
+``const`` objects) must support a regular copy constructor.  The ``block_byref``
+data structure will have copy and destroy helper routines synthesized by the
+compiler.  The copy helper will have code created to perform the copy
+constructor based on the initial stack ``block_byref`` data structure, and will
+also set the (1<<26) bit in addition to the (1<<25) bit.  The destroy helper
+will have code to do the destructor on the object stored within the supplied
+``block_byref`` heap data structure.  For example,
+
+.. code-block:: c++
+
+    __block FOO blockStorageFoo;
+
+requires the normal constructor for the embedded ``blockStorageFoo`` object:
+
+.. code-block:: c++
+
+    FOO_ctor(& _block_byref_blockStorageFoo->blockStorageFoo);
+
+and at scope termination the destructor:
+
+.. code-block:: c++
+
+    FOO_dtor(& _block_byref_blockStorageFoo->blockStorageFoo);
+
+Note that the forwarding indirection is *NOT* used.
+
+The compiler would need to generate (if used from a block literal) the following
+copy/dispose helpers:
+
+.. code-block:: c++
+
+    void _block_byref_obj_keep(struct _block_byref_blockStorageFoo *dst, struct _block_byref_blockStorageFoo *src) {
+         FOO_ctor(&dst->blockStorageFoo, &src->blockStorageFoo);
+    }
+    
+    void _block_byref_obj_dispose(struct _block_byref_blockStorageFoo *src) {
+         FOO_dtor(&src->blockStorageFoo);
+    }
+
+for the appropriately named constructor and destructor for the class/struct
+``FOO``.
+
+To support member variable and function access the compiler will synthesize a
+``const`` pointer to a block version of the ``this`` pointer.
+
+.. _RuntimeHelperFunctions:
+
+Runtime Helper Functions
+========================
+
+The runtime helper functions are described in
+``/usr/local/include/Block_private.h``.  To summarize their use, a ``Block``
+requires copy/dispose helpers if it imports any block variables, ``__block``
+storage variables, ``__attribute__((NSObject))`` variables, or C++ ``const``
+copied objects with constructor/destructors.  The (1<<26) bit is set and
+functions are generated.
+
+The block copy helper function should, for each of the variables of the type
+mentioned above, call:
+
+.. code-block:: c
+
+     _Block_object_assign(&dst->target, src->target, BLOCK_FIELD_<apropos>);
+
+in the copy helper and:
+
+.. code-block:: c
+
+    _Block_object_dispose(->target, BLOCK_FIELD_<apropos>);
+
+in the dispose helper where ``<apropos>`` is:
+
+.. code-block:: c
+
+    enum {
+        BLOCK_FIELD_IS_OBJECT   =  3,  // id, NSObject, __attribute__((NSObject)), block, ...
+        BLOCK_FIELD_IS_BLOCK    =  7,  // a block variable
+        BLOCK_FIELD_IS_BYREF    =  8,  // the on stack structure holding the __block variable
+    
+        BLOCK_FIELD_IS_WEAK     = 16,  // declared __weak
+    
+        BLOCK_BYREF_CALLER      = 128, // called from byref copy/dispose helpers
+    };
+
+and of course the constructors/destructors for ``const`` copied C++ objects.
+
+The ``block_byref`` data structure similarly requires copy/dispose helpers for
+block variables, ``__attribute__((NSObject))`` variables, or C++ ``const``
+copied objects with constructor/destructors, and again the (1<<26) bit is set
+and functions are generated in the same manner.
+
+Under ObjC we allow ``__weak`` as an attribute on ``__block`` variables, and
+this causes the addition of ``BLOCK_FIELD_IS_WEAK`` orred onto the
+``BLOCK_FIELD_IS_BYREF`` flag when copying the ``block_byref`` structure in the
+``Block`` copy helper, and onto the ``BLOCK_FIELD_<apropos>`` field within the
+``block_byref`` copy/dispose helper calls.
+
+The prototypes, and summary, of the helper functions are:
+
+.. code-block:: c
+    
+    /* Certain field types require runtime assistance when being copied to the
+       heap.  The following function is used to copy fields of types: blocks,
+       pointers to byref structures, and objects (including
+       __attribute__((NSObject)) pointers.  BLOCK_FIELD_IS_WEAK is orthogonal to
+       the other choices which are mutually exclusive.  Only in a Block copy
+       helper will one see BLOCK_FIELD_IS_BYREF.
+    */
+    void _Block_object_assign(void *destAddr, const void *object, const int flags);
+    
+    /* Similarly a compiler generated dispose helper needs to call back for each
+       field of the byref data structure.  (Currently the implementation only
+       packs one field into the byref structure but in principle there could be
+       more).  The same flags used in the copy helper should be used for each
+       call generated to this function:
+    */
+    void _Block_object_dispose(const void *object, const int flags);
+
+Copyright
+=========
+
+Copyright 2008-2010 Apple, Inc.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

Added: www-releases/trunk/7.0.0/tools/clang/docs/_sources/BlockLanguageSpec.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/BlockLanguageSpec.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/BlockLanguageSpec.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/BlockLanguageSpec.rst.txt Wed Sep 19 02:40:08 2018
@@ -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/7.0.0/tools/clang/docs/_sources/ClangCheck.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangCheck.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangCheck.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangCheck.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,36 @@
+==========
+ClangCheck
+==========
+
+`ClangCheck` is a small wrapper around :doc:`LibTooling` which can be used to
+do basic error checking and AST dumping.
+
+.. code-block:: console
+
+  $ cat <<EOF > snippet.cc
+  > void f() {
+  >   int a = 0
+  > }
+  > EOF
+  $ ~/clang/build/bin/clang-check snippet.cc -ast-dump --
+  Processing: /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc.
+  /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: error: expected ';' at end of
+        declaration
+    int a = 0
+             ^
+             ;
+  (TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>>
+    (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128')
+    (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned __int128')
+    (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list '__va_list_tag [1]')
+    (FunctionDecl 0x7ff3a302a8d0 </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> f 'void (void)'
+      (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1>
+        (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1>
+          (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int'
+            (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0))))))
+  1 error generated.
+  Error while processing snippet.cc.
+
+The '--' at the end is important as it prevents :program:`clang-check` from
+searching for a compilation database. For more information on how to setup and
+use :program:`clang-check` in a project, see :doc:`HowToSetupToolingForLLVM`.

Added: www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangCommandLineReference.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangCommandLineReference.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangCommandLineReference.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangCommandLineReference.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,2980 @@
+..
+  -------------------------------------------------------------------
+  NOTE: This file is automatically generated by running clang-tblgen
+  -gen-opt-docs. Do not edit this file by hand!!
+  -------------------------------------------------------------------
+
+=====================================
+Clang command line argument reference
+=====================================
+.. contents::
+   :local:
+
+Introduction
+============
+
+This page lists the command line arguments currently supported by the
+GCC-compatible ``clang`` and ``clang++`` drivers.
+
+
+.. program:: clang
+.. option:: -B<dir>, --prefix <arg>, --prefix=<arg>
+
+Add <dir> to search path for binaries and object files used implicitly
+
+.. option:: -F<arg>
+
+Add directory to framework include search path
+
+.. option:: -ObjC
+
+Treat source input files as Objective-C inputs
+
+.. program:: clang1
+.. option:: -ObjC++
+.. program:: clang
+
+Treat source input files as Objective-C++ inputs
+
+.. option:: -Qn, -fno-ident
+
+Do not emit metadata containing compiler name and version
+
+.. option:: -Qunused-arguments
+
+Don't emit warning for unused driver arguments
+
+.. option:: -Qy, -fident
+
+Emit metadata containing compiler name and version
+
+.. option:: -Wa,<arg>,<arg2>...
+
+Pass the comma separated arguments in <arg> to the assembler
+
+.. option:: -Wlarge-by-value-copy=<arg>
+
+.. option:: -Xarch\_<arg1> <arg2>
+
+.. option:: -Xcuda-fatbinary <arg>
+
+Pass <arg> to fatbinary invocation
+
+.. option:: -Xcuda-ptxas <arg>
+
+Pass <arg> to the ptxas assembler
+
+.. option:: -Xopenmp-target <arg>
+
+Pass <arg> to the target offloading toolchain.
+
+.. program:: clang1
+.. option:: -Xopenmp-target=<triple> <arg>
+.. program:: clang
+
+Pass <arg> to the target offloading toolchain identified by <triple>.
+
+.. option:: -Z<arg>
+
+.. option:: -a<arg>, --profile-blocks
+
+.. option:: -all\_load
+
+.. option:: -allowable\_client <arg>
+
+.. option:: --analyze
+
+Run the static analyzer
+
+.. option:: --analyze-auto
+
+.. option:: --analyzer-no-default-checks
+
+.. option:: --analyzer-output<arg>
+
+Static analyzer report output format (html\|plist\|plist-multi-file\|plist-html\|text).
+
+.. option:: -ansi, --ansi
+
+.. option:: -arch <arg>
+
+.. program:: clang1
+.. option:: -arch\_errors\_fatal
+.. program:: clang
+
+.. program:: clang2
+.. option:: -arch\_only <arg>
+.. program:: clang
+
+.. option:: -arcmt-migrate-emit-errors
+
+Emit ARC errors even if the migrator can fix them
+
+.. option:: -arcmt-migrate-report-output <arg>
+
+Output path for the plist report
+
+.. option:: --autocomplete=<arg>
+
+.. option:: -bind\_at\_load
+
+.. option:: -bundle
+
+.. program:: clang1
+.. option:: -bundle\_loader <arg>
+.. program:: clang
+
+.. option:: -cfguard
+
+Emit tables required for Windows Control Flow Guard.
+
+.. option:: -client\_name<arg>
+
+.. option:: -compatibility\_version<arg>
+
+.. option:: --config <arg>
+
+Specifies configuration file
+
+.. option:: --constant-cfstrings
+
+.. option:: -coverage, --coverage
+
+.. option:: --cuda-compile-host-device
+
+Compile CUDA code for both host and device (default).  Has no effect on non-CUDA compilations.
+
+.. option:: --cuda-device-only
+
+Compile CUDA code for device only
+
+.. option:: --cuda-gpu-arch=<arg>, --no-cuda-gpu-arch=<arg>
+
+CUDA GPU architecture (e.g. sm\_35).  May be specified more than once.
+
+.. option:: --cuda-host-only
+
+Compile CUDA code for host only.  Has no effect on non-CUDA compilations.
+
+.. option:: --cuda-include-ptx=<arg>, --no-cuda-include-ptx=<arg>
+
+Include PTX for the follwing GPU architecture (e.g. sm\_35) or 'all'. May be specified more than once.
+
+.. option:: --cuda-noopt-device-debug, --no-cuda-noopt-device-debug
+
+Enable device-side debug info generation. Disables ptxas optimizations.
+
+.. option:: -current\_version<arg>
+
+.. option:: -dead\_strip
+
+.. option:: -dependency-dot <arg>
+
+Filename to write DOT-formatted header dependencies to
+
+.. option:: -dependency-file <arg>
+
+Filename (or -) to write dependency output to
+
+.. option:: -dumpmachine
+
+.. option:: -dumpversion
+
+.. option:: --dyld-prefix=<arg>, --dyld-prefix <arg>
+
+.. option:: -dylib\_file <arg>
+
+.. option:: -dylinker
+
+.. program:: clang1
+.. option:: -dylinker\_install\_name<arg>
+.. program:: clang
+
+.. option:: -dynamic
+
+.. option:: -dynamiclib
+
+.. option:: -emit-ast
+
+Emit Clang AST files for source inputs
+
+.. option:: -exported\_symbols\_list <arg>
+
+.. option:: -faligned-new=<arg>
+
+.. option:: -fcuda-approx-transcendentals, -fno-cuda-approx-transcendentals
+
+Use approximate transcendental functions
+
+.. option:: -fcuda-flush-denormals-to-zero, -fno-cuda-flush-denormals-to-zero
+
+Flush denormal floating point values to zero in CUDA device mode.
+
+.. option:: -fcuda-rdc, -fno-cuda-rdc
+
+Generate relocatable device code, also known as separate compilation mode.
+
+.. option:: -fcuda-short-ptr, -fno-cuda-short-ptr
+
+Use 32-bit pointers for accessing const/local/shared address spaces.
+
+.. option:: -ffixed-r19
+
+Reserve register r19 (Hexagon only)
+
+.. option:: -fheinous-gnu-extensions
+
+.. option:: -flat\_namespace
+
+.. option:: -fopenmp-targets=<arg1>,<arg2>...
+
+Specify comma-separated list of triples OpenMP offloading targets to be supported
+
+.. option:: -force\_cpusubtype\_ALL
+
+.. program:: clang1
+.. option:: -force\_flat\_namespace
+.. program:: clang
+
+.. program:: clang2
+.. option:: -force\_load <arg>
+.. program:: clang
+
+.. option:: -framework <arg>
+
+.. option:: -frtlib-add-rpath, -fno-rtlib-add-rpath
+
+Add -rpath with architecture-specific resource directory to the linker flags
+
+.. option:: --gcc-toolchain=<arg>, -gcc-toolchain <arg>
+
+Use the gcc toolchain at the given directory
+
+.. option:: -gcodeview
+
+Generate CodeView debug information
+
+.. option:: -headerpad\_max\_install\_names<arg>
+
+.. option:: -help, --help
+
+Display available options
+
+.. option:: --help-hidden
+
+Display help for hidden options
+
+.. option:: --hip-link
+
+Link clang-offload-bundler bundles for HIP
+
+.. option:: -image\_base <arg>
+
+.. option:: -index-header-map
+
+Make the next included directory (-I or -F) an indexer header map
+
+.. option:: -init <arg>
+
+.. option:: -install\_name <arg>
+
+.. option:: -keep\_private\_externs
+
+.. option:: -lazy\_framework <arg>
+
+.. program:: clang1
+.. option:: -lazy\_library <arg>
+.. program:: clang
+
+.. option:: -mbig-endian, -EB
+
+.. option:: --migrate
+
+Run the migrator
+
+.. option:: -mios-simulator-version-min=<arg>, -miphonesimulator-version-min=<arg>
+
+.. option:: -mlinker-version=<arg>
+
+.. option:: -mlittle-endian, -EL
+
+.. option:: -mllvm <arg>
+
+Additional arguments to forward to LLVM's option processing
+
+.. option:: -module-dependency-dir <arg>
+
+Directory to dump module dependencies to
+
+.. option:: -mtvos-simulator-version-min=<arg>, -mappletvsimulator-version-min=<arg>
+
+.. option:: -multi\_module
+
+.. option:: -multiply\_defined <arg>
+
+.. program:: clang1
+.. option:: -multiply\_defined\_unused <arg>
+.. program:: clang
+
+.. option:: -mwatchos-simulator-version-min=<arg>, -mwatchsimulator-version-min=<arg>
+
+.. option:: --no-cuda-version-check
+
+Don't error out if the detected version of the CUDA install is too low for the requested CUDA gpu architecture.
+
+.. option:: -no-integrated-cpp, --no-integrated-cpp
+
+.. option:: -no\_dead\_strip\_inits\_and\_terms
+
+.. option:: -nobuiltininc
+
+Disable builtin #include directories
+
+.. option:: -nocudainc
+
+.. option:: -nocudalib
+
+.. option:: -nodefaultlibs
+
+.. option:: -nofixprebinding
+
+.. option:: -nolibc
+
+.. option:: -nomultidefs
+
+.. option:: -nopie, -no-pie
+
+.. option:: -noprebind
+
+.. option:: -noseglinkedit
+
+.. option:: -nostartfiles
+
+.. option:: -nostdinc, --no-standard-includes
+
+.. program:: clang1
+.. option:: -nostdinc++
+.. program:: clang
+
+Disable standard #include directories for the C++ standard library
+
+.. option:: -nostdlib, --no-standard-libraries
+
+.. program:: clang1
+.. option:: -nostdlib++
+.. program:: clang
+
+.. option:: -nostdlibinc
+
+.. option:: -o<file>, --output <arg>, --output=<arg>
+
+Write output to <file>
+
+.. option:: -objcmt-atomic-property
+
+Make migration to 'atomic' properties
+
+.. option:: -objcmt-migrate-all
+
+Enable migration to modern ObjC
+
+.. option:: -objcmt-migrate-annotation
+
+Enable migration to property and method annotations
+
+.. option:: -objcmt-migrate-designated-init
+
+Enable migration to infer NS\_DESIGNATED\_INITIALIZER for initializer methods
+
+.. option:: -objcmt-migrate-instancetype
+
+Enable migration to infer instancetype for method result type
+
+.. option:: -objcmt-migrate-literals
+
+Enable migration to modern ObjC literals
+
+.. option:: -objcmt-migrate-ns-macros
+
+Enable migration to NS\_ENUM/NS\_OPTIONS macros
+
+.. option:: -objcmt-migrate-property
+
+Enable migration to modern ObjC property
+
+.. option:: -objcmt-migrate-property-dot-syntax
+
+Enable migration of setter/getter messages to property-dot syntax
+
+.. option:: -objcmt-migrate-protocol-conformance
+
+Enable migration to add protocol conformance on classes
+
+.. option:: -objcmt-migrate-readonly-property
+
+Enable migration to modern ObjC readonly property
+
+.. option:: -objcmt-migrate-readwrite-property
+
+Enable migration to modern ObjC readwrite property
+
+.. option:: -objcmt-migrate-subscripting
+
+Enable migration to modern ObjC subscripting
+
+.. option:: -objcmt-ns-nonatomic-iosonly
+
+Enable migration to use NS\_NONATOMIC\_IOSONLY macro for setting property's 'atomic' attribute
+
+.. option:: -objcmt-returns-innerpointer-property
+
+Enable migration to annotate property with NS\_RETURNS\_INNER\_POINTER
+
+.. option:: -objcmt-whitelist-dir-path=<arg>, -objcmt-white-list-dir-path=<arg>
+
+Only modify files with a filename contained in the provided directory path
+
+.. option:: -object
+
+.. option:: -p, --profile
+
+.. option:: -pagezero\_size<arg>
+
+.. option:: -pg
+
+Enable mcount instrumentation
+
+.. option:: -pie
+
+.. option:: -pipe, --pipe
+
+Use pipes between commands, when possible
+
+.. option:: -prebind
+
+.. program:: clang1
+.. option:: -prebind\_all\_twolevel\_modules
+.. program:: clang
+
+.. option:: -preload
+
+.. option:: --print-diagnostic-categories
+
+.. option:: -print-file-name=<file>, --print-file-name=<file>, --print-file-name <arg>
+
+Print the full library path of <file>
+
+.. option:: -print-ivar-layout
+
+Enable Objective-C Ivar layout bitmap print trace
+
+.. option:: -print-libgcc-file-name, --print-libgcc-file-name
+
+Print the library path for the currently used compiler runtime library ("libgcc.a" or "libclang\_rt.builtins.\*.a")
+
+.. option:: -print-multi-directory, --print-multi-directory
+
+.. option:: -print-multi-lib, --print-multi-lib
+
+.. option:: -print-prog-name=<name>, --print-prog-name=<name>, --print-prog-name <arg>
+
+Print the full program path of <name>
+
+.. option:: -print-resource-dir, --print-resource-dir
+
+Print the resource directory pathname
+
+.. option:: -print-search-dirs, --print-search-dirs
+
+Print the paths used for finding libraries and programs
+
+.. option:: -private\_bundle
+
+.. option:: -pthread, -no-pthread
+
+Support POSIX threads in generated code
+
+.. option:: -pthreads
+
+.. option:: -rdynamic
+
+.. option:: -read\_only\_relocs <arg>
+
+.. option:: -relocatable-pch, --relocatable-pch
+
+Whether to build a relocatable precompiled header
+
+.. option:: -remap
+
+.. option:: -rewrite-legacy-objc
+
+Rewrite Legacy Objective-C source to C++
+
+.. option:: -rtlib=<arg>, --rtlib=<arg>, --rtlib <arg>
+
+Compiler runtime library to use
+
+.. option:: -save-stats=<arg>, --save-stats=<arg>, -save-stats (equivalent to -save-stats=cwd), --save-stats (equivalent to -save-stats=cwd)
+
+Save llvm statistics.
+
+.. option:: -save-temps=<arg>, --save-temps=<arg>, -save-temps (equivalent to -save-temps=cwd), --save-temps (equivalent to -save-temps=cwd)
+
+Save intermediate compilation results.
+
+.. option:: -sectalign <arg1> <arg2> <arg3>
+
+.. option:: -sectcreate <arg1> <arg2> <arg3>
+
+.. option:: -sectobjectsymbols <arg1> <arg2>
+
+.. option:: -sectorder <arg1> <arg2> <arg3>
+
+.. option:: -seg1addr<arg>
+
+.. option:: -seg\_addr\_table <arg>
+
+.. program:: clang1
+.. option:: -seg\_addr\_table\_filename <arg>
+.. program:: clang
+
+.. option:: -segaddr <arg1> <arg2>
+
+.. option:: -segcreate <arg1> <arg2> <arg3>
+
+.. option:: -seglinkedit
+
+.. option:: -segprot <arg1> <arg2> <arg3>
+
+.. option:: -segs\_read\_<arg>
+
+.. program:: clang1
+.. option:: -segs\_read\_only\_addr <arg>
+.. program:: clang
+
+.. program:: clang2
+.. option:: -segs\_read\_write\_addr <arg>
+.. program:: clang
+
+.. option:: -serialize-diagnostics <arg>, --serialize-diagnostics <arg>
+
+Serialize compiler diagnostics to a file
+
+.. option:: -shared, --shared
+
+.. option:: -shared-libgcc
+
+.. option:: -shared-libsan, -shared-libasan
+
+.. option:: -single\_module
+
+.. option:: -specs=<arg>, --specs=<arg>
+
+.. option:: -static, --static
+
+.. option:: -static-libgcc
+
+.. option:: -static-libsan
+
+.. option:: -static-libstdc++
+
+.. option:: -std-default=<arg>
+
+.. option:: -stdlib=<arg>, --stdlib=<arg>, --stdlib <arg>
+
+C++ standard library to use
+
+.. option:: -sub\_library<arg>
+
+.. program:: clang1
+.. option:: -sub\_umbrella<arg>
+.. program:: clang
+
+.. option:: --sysroot=<arg>, --sysroot <arg>
+
+.. option:: --target-help
+
+.. option:: --target=<arg>, -target <arg>
+
+Generate code for the given target
+
+.. option:: -time
+
+Time individual commands
+
+.. option:: -traditional, --traditional
+
+.. option:: -traditional-cpp, --traditional-cpp
+
+Enable some traditional CPP emulation
+
+.. option:: -twolevel\_namespace
+
+.. program:: clang1
+.. option:: -twolevel\_namespace\_hints
+.. program:: clang
+
+.. option:: -umbrella <arg>
+
+.. option:: -unexported\_symbols\_list <arg>
+
+.. option:: -v, --verbose
+
+Show commands to run and use verbose output
+
+.. option:: --verify-debug-info
+
+Verify the binary representation of debug output
+
+.. option:: --version
+
+Print version information
+
+.. option:: -w, --no-warnings
+
+Suppress all warnings
+
+.. option:: -weak-l<arg>
+
+.. option:: -weak\_framework <arg>
+
+.. program:: clang1
+.. option:: -weak\_library <arg>
+.. program:: clang
+
+.. program:: clang2
+.. option:: -weak\_reference\_mismatches <arg>
+.. program:: clang
+
+.. option:: -whatsloaded
+
+.. option:: -whyload
+
+.. option:: -working-directory<arg>, -working-directory=<arg>
+
+Resolve file paths relative to the specified directory
+
+.. option:: -x<language>, --language <arg>, --language=<arg>
+
+Treat subsequent input files as having type <language>
+
+.. option:: -y<arg>
+
+Actions
+=======
+The action to perform on the input.
+
+.. option:: -E, --preprocess
+
+Only run the preprocessor
+
+.. option:: -S, --assemble
+
+Only run preprocess and compilation steps
+
+.. option:: -c, --compile
+
+Only run preprocess, compile, and assemble steps
+
+.. option:: -emit-llvm
+
+Use the LLVM representation for assembler and object files
+
+.. option:: -fsyntax-only
+
+.. option:: -module-file-info
+
+Provide information about a particular module file
+
+.. option:: --precompile
+
+Only precompile the input
+
+.. option:: -rewrite-objc
+
+Rewrite Objective-C source to C++
+
+.. option:: -verify-pch
+
+Load and verify that a pre-compiled header file is not stale
+
+Compilation flags
+=================
+
+Flags controlling the behavior of Clang during compilation. These flags have
+no effect during actions that do not perform compilation.
+
+.. option:: -Xassembler <arg>
+
+Pass <arg> to the assembler
+
+.. option:: -Xclang <arg>
+
+Pass <arg> to the clang compiler
+
+.. option:: -fclang-abi-compat=<version>
+
+Attempt to match the ABI of Clang <version>
+
+.. option:: -fcomment-block-commands=<arg>,<arg2>...
+
+Treat each comma separated argument in <arg> as a documentation comment block command
+
+.. option:: -fcomplete-member-pointers, -fno-complete-member-pointers
+
+Require member pointer base types to be complete if they would be significant under the Microsoft ABI
+
+.. option:: -fcrash-diagnostics-dir=<arg>
+
+.. option:: -fdeclspec, -fno-declspec
+
+Allow \_\_declspec as a keyword
+
+.. option:: -fdepfile-entry=<arg>
+
+.. option:: -fdiagnostics-fixit-info, -fno-diagnostics-fixit-info
+
+.. option:: -fdiagnostics-format=<arg>
+
+.. option:: -fdiagnostics-parseable-fixits
+
+Print fix-its in machine parseable form
+
+.. option:: -fdiagnostics-print-source-range-info
+
+Print source range spans in numeric form
+
+.. option:: -fdiagnostics-show-category=<arg>
+
+.. option:: -fdiscard-value-names, -fno-discard-value-names
+
+Discard value names in LLVM IR
+
+.. option:: -fexperimental-isel, -fno-experimental-isel
+
+Enables the experimental global instruction selector
+
+.. option:: -fexperimental-new-pass-manager, -fno-experimental-new-pass-manager
+
+Enables an experimental new pass manager in LLVM.
+
+.. option:: -ffine-grained-bitfield-accesses, -fno-fine-grained-bitfield-accesses
+
+Use separate accesses for consecutive bitfield runs with legal widths and alignments.
+
+.. option:: -finline-functions, -fno-inline-functions
+
+Inline suitable functions
+
+.. option:: -finline-hint-functions
+
+Inline functions which are (explicitly or implicitly) marked inline
+
+.. option:: -fno-crash-diagnostics
+
+Disable auto-generation of preprocessed source files and a script for reproduction during a clang crash
+
+.. option:: -fno-sanitize-blacklist
+
+Don't use blacklist file for sanitizers
+
+.. option:: -fparse-all-comments
+
+.. option:: -fsanitize-address-field-padding=<arg>
+
+Level of field padding for AddressSanitizer
+
+.. option:: -fsanitize-address-globals-dead-stripping
+
+Enable linker dead stripping of globals in AddressSanitizer
+
+.. option:: -fsanitize-address-poison-class-member-array-new-cookie, -fno-sanitize-address-poison-class-member-array-new-cookie
+
+Enable poisoning array cookies when using class member operator new\[\] in AddressSanitizer
+
+.. option:: -fsanitize-address-use-after-scope, -fno-sanitize-address-use-after-scope
+
+Enable use-after-scope detection in AddressSanitizer
+
+.. option:: -fsanitize-blacklist=<arg>
+
+Path to blacklist file for sanitizers
+
+.. option:: -fsanitize-cfi-cross-dso, -fno-sanitize-cfi-cross-dso
+
+Enable control flow integrity (CFI) checks for cross-DSO calls.
+
+.. option:: -fsanitize-cfi-icall-generalize-pointers
+
+Generalize pointers in CFI indirect call type signature checks
+
+.. option:: -fsanitize-coverage=<arg1>,<arg2>..., -fno-sanitize-coverage=<arg1>,<arg2>...
+
+Specify the type of coverage instrumentation for Sanitizers
+
+.. option:: -fsanitize-link-c++-runtime
+
+.. option:: -fsanitize-memory-track-origins, -fno-sanitize-memory-track-origins
+
+Enable origins tracking in MemorySanitizer
+
+.. program:: clang1
+.. option:: -fsanitize-memory-track-origins=<arg>
+.. program:: clang
+
+Enable origins tracking in MemorySanitizer
+
+.. option:: -fsanitize-memory-use-after-dtor, -fno-sanitize-memory-use-after-dtor
+
+Enable use-after-destroy detection in MemorySanitizer
+
+.. option:: -fsanitize-minimal-runtime, -fno-sanitize-minimal-runtime
+
+.. option:: -fsanitize-recover, -fno-sanitize-recover
+
+.. program:: clang1
+.. option:: -fsanitize-recover=<arg1>,<arg2>..., -fno-sanitize-recover=<arg1>,<arg2>...
+.. program:: clang
+
+Enable recovery for specified sanitizers
+
+.. option:: -fsanitize-stats, -fno-sanitize-stats
+
+Enable sanitizer statistics gathering.
+
+.. option:: -fsanitize-thread-atomics, -fno-sanitize-thread-atomics
+
+Enable atomic operations instrumentation in ThreadSanitizer (default)
+
+.. option:: -fsanitize-thread-func-entry-exit, -fno-sanitize-thread-func-entry-exit
+
+Enable function entry/exit instrumentation in ThreadSanitizer (default)
+
+.. option:: -fsanitize-thread-memory-access, -fno-sanitize-thread-memory-access
+
+Enable memory access instrumentation in ThreadSanitizer (default)
+
+.. option:: -fsanitize-trap=<arg1>,<arg2>..., -fno-sanitize-trap=<arg1>,<arg2>...
+
+Enable trapping for specified sanitizers
+
+.. option:: -fsanitize-undefined-strip-path-components=<number>
+
+Strip (or keep only, if negative) a given number of path components when emitting check metadata.
+
+.. option:: -fsanitize-undefined-trap-on-error, -fno-sanitize-undefined-trap-on-error
+
+.. option:: -fsanitize=<check>,<arg2>..., -fno-sanitize=<arg1>,<arg2>...
+
+Turn on runtime checks for various forms of undefined or suspicious behavior. See user manual for available checks
+
+.. option:: -moutline, -mno-outline
+
+Enable function outlining (AArch64 only)
+
+.. option:: --param <arg>, --param=<arg>
+
+.. option:: -std=<arg>, --std=<arg>, --std <arg>
+
+Language standard to compile for
+
+Preprocessor flags
+~~~~~~~~~~~~~~~~~~
+
+Flags controlling the behavior of the Clang preprocessor.
+
+.. option:: -C, --comments
+
+Include comments in preprocessed output
+
+.. option:: -CC, --comments-in-macros
+
+Include comments from within macros in preprocessed output
+
+.. option:: -D<macro>=<value>, --define-macro <arg>, --define-macro=<arg>
+
+Define <macro> to <value> (or 1 if <value> omitted)
+
+.. option:: -H, --trace-includes
+
+Show header includes and nesting depth
+
+.. option:: -P, --no-line-commands
+
+Disable linemarker output in -E mode
+
+.. option:: -U<macro>, --undefine-macro <arg>, --undefine-macro=<arg>
+
+Undefine macro <macro>
+
+.. option:: -Wp,<arg>,<arg2>...
+
+Pass the comma separated arguments in <arg> to the preprocessor
+
+.. option:: -Xpreprocessor <arg>
+
+Pass <arg> to the preprocessor
+
+Include path management
+-----------------------
+
+Flags controlling how ``#include``\s are resolved to files.
+
+.. option:: -I<dir>, --include-directory <arg>, --include-directory=<arg>
+
+Add directory to include search path
+
+.. option:: -I-, --include-barrier
+
+Restrict all prior -I flags to double-quoted inclusion and remove current directory from include path
+
+.. option:: --cuda-path-ignore-env
+
+Ignore environment variables to detect CUDA installation
+
+.. option:: --cuda-path=<arg>
+
+CUDA installation path
+
+.. option:: -cxx-isystem<directory>
+
+Add directory to the C++ SYSTEM include search path
+
+.. option:: -fbuild-session-file=<file>
+
+Use the last modification time of <file> as the build session timestamp
+
+.. option:: -fbuild-session-timestamp=<time since Epoch in seconds>
+
+Time when the current build session started
+
+.. option:: -fmodule-file=\[<name>=\]<file>
+
+Specify the mapping of module name to precompiled module file, or load a module file if name is omitted.
+
+.. option:: -fmodules-cache-path=<directory>
+
+Specify the module cache path
+
+.. option:: -fmodules-disable-diagnostic-validation
+
+Disable validation of the diagnostic options when loading the module
+
+.. option:: -fmodules-prune-after=<seconds>
+
+Specify the interval (in seconds) after which a module file will be considered unused
+
+.. option:: -fmodules-prune-interval=<seconds>
+
+Specify the interval (in seconds) between attempts to prune the module cache
+
+.. option:: -fmodules-user-build-path <directory>
+
+Specify the module user build path
+
+.. option:: -fmodules-validate-once-per-build-session
+
+Don't verify input files for the modules if the module has been successfully validated or loaded during this build session
+
+.. option:: -fmodules-validate-system-headers, -fno-modules-validate-system-headers
+
+Validate the system headers that a module depends on when loading the module
+
+.. option:: -fprebuilt-module-path=<directory>
+
+Specify the prebuilt module path
+
+.. option:: -idirafter<arg>, --include-directory-after <arg>, --include-directory-after=<arg>
+
+Add directory to AFTER include search path
+
+.. option:: -iframework<arg>
+
+Add directory to SYSTEM framework search path
+
+.. option:: -iframeworkwithsysroot<directory>
+
+Add directory to SYSTEM framework search path, absolute paths are relative to -isysroot
+
+.. option:: -imacros<file>, --imacros<file>, --imacros=<arg>
+
+Include macros from file before parsing
+
+.. option:: -include<file>, --include<file>, --include=<arg>
+
+Include file before parsing
+
+.. option:: -include-pch <file>
+
+Include precompiled header file
+
+.. option:: -iprefix<dir>, --include-prefix <arg>, --include-prefix=<arg>
+
+Set the -iwithprefix/-iwithprefixbefore prefix
+
+.. option:: -iquote<directory>
+
+Add directory to QUOTE include search path
+
+.. option:: -isysroot<dir>
+
+Set the system root directory (usually /)
+
+.. option:: -isystem<directory>
+
+Add directory to SYSTEM include search path
+
+.. option:: -isystem-after<directory>
+
+Add directory to end of the SYSTEM include search path
+
+.. option:: -ivfsoverlay<arg>
+
+Overlay the virtual filesystem described by file over the real file system
+
+.. option:: -iwithprefix<dir>, --include-with-prefix <arg>, --include-with-prefix-after <arg>, --include-with-prefix-after=<arg>, --include-with-prefix=<arg>
+
+Set directory to SYSTEM include search path with prefix
+
+.. option:: -iwithprefixbefore<dir>, --include-with-prefix-before <arg>, --include-with-prefix-before=<arg>
+
+Set directory to include search path with prefix
+
+.. option:: -iwithsysroot<directory>
+
+Add directory to SYSTEM include search path, absolute paths are relative to -isysroot
+
+.. option:: --ptxas-path=<arg>
+
+Path to ptxas (used for compiling CUDA code)
+
+.. option:: --system-header-prefix=<prefix>, --no-system-header-prefix=<prefix>, --system-header-prefix <arg>
+
+Treat all #include paths starting with <prefix> as including a system header.
+
+Dependency file generation
+--------------------------
+
+Flags controlling generation of a dependency file for ``make``-like build
+systems.
+
+.. option:: -M, --dependencies
+
+Like -MD, but also implies -E and writes to stdout by default
+
+.. option:: -MD, --write-dependencies
+
+Write a depfile containing user and system headers
+
+.. option:: -MF<file>
+
+Write depfile output from -MMD, -MD, -MM, or -M to <file>
+
+.. option:: -MG, --print-missing-file-dependencies
+
+Add missing headers to depfile
+
+.. option:: -MJ<arg>
+
+Write a compilation database entry per input
+
+.. option:: -MM, --user-dependencies
+
+Like -MMD, but also implies -E and writes to stdout by default
+
+.. option:: -MMD, --write-user-dependencies
+
+Write a depfile containing user headers
+
+.. option:: -MP
+
+Create phony target for each dependency (other than main file)
+
+.. option:: -MQ<arg>
+
+Specify name of main file output to quote in depfile
+
+.. option:: -MT<arg>
+
+Specify name of main file output in depfile
+
+.. option:: -MV
+
+Use NMake/Jom format for the depfile
+
+Dumping preprocessor state
+--------------------------
+
+Flags allowing the state of the preprocessor to be dumped in various ways.
+
+.. option:: -d
+
+.. program:: clang1
+.. option:: -d<arg>
+.. program:: clang
+
+.. option:: -dA
+
+.. option:: -dD
+
+Print macro definitions in -E mode in addition to normal output
+
+.. option:: -dI
+
+Print include directives in -E mode in addition to normal output
+
+.. option:: -dM
+
+Print macro definitions in -E mode instead of normal output
+
+Diagnostic flags
+~~~~~~~~~~~~~~~~
+
+Flags controlling which warnings, errors, and remarks Clang will generate.
+See the :doc:`full list of warning and remark flags <DiagnosticsReference>`.
+
+.. option:: -R<remark>
+
+Enable the specified remark
+
+.. option:: -Rpass-analysis=<arg>
+
+Report transformation analysis from optimization passes whose name matches the given POSIX regular expression
+
+.. option:: -Rpass-missed=<arg>
+
+Report missed transformations by optimization passes whose name matches the given POSIX regular expression
+
+.. option:: -Rpass=<arg>
+
+Report transformations performed by optimization passes whose name matches the given POSIX regular expression
+
+.. option:: -W<warning>, --extra-warnings, --warn-<arg>, --warn-=<arg>
+
+Enable the specified warning
+
+.. option:: -Wdeprecated, -Wno-deprecated
+
+Enable warnings for deprecated constructs and define \_\_DEPRECATED
+
+.. option:: -Wnonportable-cfstrings<arg>, -Wno-nonportable-cfstrings<arg>
+
+Target-independent compilation options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. option:: -Wframe-larger-than=<arg>
+
+.. option:: -fPIC, -fno-PIC
+
+.. option:: -fPIE, -fno-PIE
+
+.. option:: -faccess-control, -fno-access-control
+
+.. option:: -faddrsig, -fno-addrsig
+
+Emit an address-significance table
+
+.. option:: -falign-functions, -fno-align-functions
+
+.. program:: clang1
+.. option:: -falign-functions=<arg>
+.. program:: clang
+
+.. program:: clang1
+.. option:: -faligned-allocation, -faligned-new, -fno-aligned-allocation
+.. program:: clang
+
+Enable C++17 aligned allocation functions
+
+.. option:: -fallow-editor-placeholders, -fno-allow-editor-placeholders
+
+Treat editor placeholders as valid source code
+
+.. option:: -fallow-unsupported
+
+.. option:: -faltivec, -fno-altivec
+
+.. option:: -fansi-escape-codes
+
+Use ANSI escape codes for diagnostics
+
+.. option:: -fapple-kext, -findirect-virtual-calls, -fterminated-vtables
+
+Use Apple's kernel extensions ABI
+
+.. option:: -fapple-pragma-pack, -fno-apple-pragma-pack
+
+Enable Apple gcc-compatible #pragma pack handling
+
+.. option:: -fapplication-extension, -fno-application-extension
+
+Restrict code to those available for App Extensions
+
+.. option:: -fasm, -fno-asm
+
+.. option:: -fasm-blocks, -fno-asm-blocks
+
+.. option:: -fassociative-math, -fno-associative-math
+
+.. option:: -fassume-sane-operator-new, -fno-assume-sane-operator-new
+
+.. option:: -fast
+
+.. option:: -fastcp
+
+.. option:: -fastf
+
+.. option:: -fasynchronous-unwind-tables, -fno-asynchronous-unwind-tables
+
+.. option:: -fautolink, -fno-autolink
+
+.. option:: -fblocks, -fno-blocks
+
+Enable the 'blocks' language feature
+
+.. option:: -fbootclasspath=<arg>, --bootclasspath <arg>, --bootclasspath=<arg>
+
+.. option:: -fborland-extensions, -fno-borland-extensions
+
+Accept non-standard constructs supported by the Borland compiler
+
+.. option:: -fbracket-depth=<arg>
+
+.. option:: -fbuiltin, -fno-builtin
+
+.. option:: -fbuiltin-module-map
+
+Load the clang builtins module map file.
+
+.. option:: -fcaret-diagnostics, -fno-caret-diagnostics
+
+.. option:: -fcf-protection=<arg>, -fcf-protection (equivalent to -fcf-protection=full)
+
+Instrument control-flow architecture protection. Options: return, branch, full, none.
+
+.. option:: -fchar8\_t, -fno-char8\_t
+
+Enable C++ builtin type char8\_t
+
+.. option:: -fclasspath=<arg>, --CLASSPATH <arg>, --CLASSPATH=<arg>, --classpath <arg>, --classpath=<arg>
+
+.. option:: -fcolor-diagnostics, -fno-color-diagnostics
+
+Use colors in diagnostics
+
+.. option:: -fcommon, -fno-common
+
+.. option:: -fcompile-resource=<arg>, --resource <arg>, --resource=<arg>
+
+.. option:: -fconstant-cfstrings, -fno-constant-cfstrings
+
+.. option:: -fconstant-string-class=<arg>
+
+.. option:: -fconstexpr-backtrace-limit=<arg>
+
+.. option:: -fconstexpr-depth=<arg>
+
+.. option:: -fconstexpr-steps=<arg>
+
+.. option:: -fcoroutines-ts, -fno-coroutines-ts
+
+Enable support for the C++ Coroutines TS
+
+.. option:: -fcoverage-mapping, -fno-coverage-mapping
+
+Generate coverage mapping to enable code coverage analysis
+
+.. option:: -fcreate-profile
+
+.. option:: -fcxx-exceptions, -fno-cxx-exceptions
+
+Enable C++ exceptions
+
+.. option:: -fcxx-modules, -fno-cxx-modules
+
+.. option:: -fdata-sections, -fno-data-sections
+
+Place each data in its own section (ELF Only)
+
+.. option:: -fdebug-info-for-profiling, -fno-debug-info-for-profiling
+
+Emit extra debug info to make sample profile more accurate.
+
+.. option:: -fdebug-macro, -fno-debug-macro
+
+Emit macro debug information
+
+.. option:: -fdebug-pass-arguments
+
+.. option:: -fdebug-pass-structure
+
+.. option:: -fdebug-prefix-map=<arg>
+
+remap file source paths in debug info
+
+.. option:: -fdebug-types-section, -fno-debug-types-section
+
+Place debug types in their own section (ELF Only)
+
+.. option:: -fdelayed-template-parsing, -fno-delayed-template-parsing
+
+Parse templated function definitions at the end of the translation unit
+
+.. option:: -fdelete-null-pointer-checks, -fno-delete-null-pointer-checks
+
+Treat usage of null pointers as undefined behavior.
+
+.. option:: -fdenormal-fp-math=<arg>
+
+.. option:: -fdiagnostics-absolute-paths
+
+Print absolute paths in diagnostics
+
+.. option:: -fdiagnostics-color, -fno-diagnostics-color
+
+.. program:: clang1
+.. option:: -fdiagnostics-color=<arg>
+.. program:: clang
+
+.. option:: -fdiagnostics-hotness-threshold=<number>
+
+Prevent optimization remarks from being output if they do not have at least this profile count
+
+.. option:: -fdiagnostics-show-hotness, -fno-diagnostics-show-hotness
+
+Enable profile hotness information in diagnostic line
+
+.. option:: -fdiagnostics-show-note-include-stack, -fno-diagnostics-show-note-include-stack
+
+Display include stacks for diagnostic notes
+
+.. option:: -fdiagnostics-show-option, -fno-diagnostics-show-option
+
+Print option name with mappable diagnostics
+
+.. option:: -fdiagnostics-show-template-tree
+
+Print a template comparison tree for differing templates
+
+.. option:: -fdigraphs, -fno-digraphs
+
+Enable alternative token representations '<:', ':>', '<%', '%>', '%:', '%:%:' (default)
+
+.. option:: -fdollars-in-identifiers, -fno-dollars-in-identifiers
+
+Allow '$' in identifiers
+
+.. option:: -fdouble-square-bracket-attributes, -fno-double-square-bracket-attributes
+
+Enable '\[\[\]\]' attributes in all C and C++ language modes
+
+.. option:: -fdwarf-directory-asm, -fno-dwarf-directory-asm
+
+.. option:: -fdwarf-exceptions
+
+Use DWARF style exceptions
+
+.. option:: -felide-constructors, -fno-elide-constructors
+
+.. option:: -feliminate-unused-debug-symbols, -fno-eliminate-unused-debug-symbols
+
+.. option:: -fembed-bitcode=<option>, -fembed-bitcode (equivalent to -fembed-bitcode=all), -fembed-bitcode-marker (equivalent to -fembed-bitcode=marker)
+
+Embed LLVM bitcode (option: off, all, bitcode, marker)
+
+.. option:: -femit-all-decls
+
+Emit all declarations, even if unused
+
+.. option:: -femulated-tls, -fno-emulated-tls
+
+Use emutls functions to access thread\_local variables
+
+.. option:: -fencoding=<arg>, --encoding <arg>, --encoding=<arg>
+
+.. option:: -ferror-limit=<arg>
+
+.. option:: -fescaping-block-tail-calls, -fno-escaping-block-tail-calls
+
+.. option:: -fexceptions, -fno-exceptions
+
+Enable support for exception handling
+
+.. option:: -fexec-charset=<arg>
+
+.. option:: -fextdirs=<arg>, --extdirs <arg>, --extdirs=<arg>
+
+.. option:: -ffast-math, -fno-fast-math
+
+Allow aggressive, lossy floating-point optimizations
+
+.. option:: -ffinite-math-only, -fno-finite-math-only
+
+.. option:: -ffixed-point, -fno-fixed-point
+
+Enable fixed point types
+
+.. option:: -ffor-scope, -fno-for-scope
+
+.. option:: -fforce-emit-vtables, -fno-force-emit-vtables
+
+Emits more virtual tables to improve devirtualization
+
+.. option:: -fforce-enable-int128, -fno-force-enable-int128
+
+Enable support for int128\_t type
+
+.. option:: -ffp-contract=<arg>
+
+Form fused FP ops (e.g. FMAs): fast (everywhere) \| on (according to FP\_CONTRACT pragma, default) \| off (never fuse)
+
+.. option:: -ffreestanding
+
+Assert that the compilation takes place in a freestanding environment
+
+.. option:: -ffunction-sections, -fno-function-sections
+
+Place each function in its own section (ELF Only)
+
+.. option:: -fgnu-inline-asm, -fno-gnu-inline-asm
+
+.. option:: -fgnu-keywords, -fno-gnu-keywords
+
+Allow GNU-extension keywords regardless of language standard
+
+.. option:: -fgnu-runtime
+
+Generate output compatible with the standard GNU Objective-C runtime
+
+.. option:: -fgnu89-inline, -fno-gnu89-inline
+
+Use the gnu89 inline semantics
+
+.. option:: -fhonor-infinities, -fhonor-infinites, -fno-honor-infinities
+
+.. option:: -fhonor-nans, -fno-honor-nans
+
+.. option:: -fhosted
+
+.. option:: -fimplicit-module-maps, -fmodule-maps, -fno-implicit-module-maps
+
+Implicitly search the file system for module map files.
+
+.. option:: -fimplicit-modules, -fno-implicit-modules
+
+.. option:: -finput-charset=<arg>
+
+.. option:: -finstrument-function-entry-bare
+
+Instrument function entry only, after inlining, without arguments to the instrumentation call
+
+.. option:: -finstrument-functions
+
+Generate calls to instrument function entry and exit
+
+.. option:: -finstrument-functions-after-inlining
+
+Like -finstrument-functions, but insert the calls after inlining
+
+.. option:: -fintegrated-as, -fno-integrated-as, -integrated-as
+
+Enable the integrated assembler
+
+.. option:: -fjump-tables, -fno-jump-tables
+
+.. option:: -flax-vector-conversions, -fno-lax-vector-conversions
+
+.. option:: -flimited-precision=<arg>
+
+.. option:: -flto, -fno-lto
+
+Enable LTO in 'full' mode
+
+.. option:: -flto-jobs=<arg>
+
+Controls the backend parallelism of -flto=thin (default of 0 means the number of threads will be derived from the number of CPUs detected)
+
+.. program:: clang1
+.. option:: -flto=<arg>
+.. program:: clang
+
+Set LTO mode to either 'full' or 'thin'
+
+.. option:: -fmacro-backtrace-limit=<arg>
+
+.. option:: -fmath-errno, -fno-math-errno
+
+Require math functions to indicate errors by setting errno
+
+.. option:: -fmax-type-align=<arg>
+
+Specify the maximum alignment to enforce on pointers lacking an explicit alignment
+
+.. option:: -fmerge-all-constants, -fno-merge-all-constants
+
+Allow merging of constants
+
+.. option:: -fmessage-length=<arg>
+
+.. option:: -fmodule-file-deps, -fno-module-file-deps
+
+.. option:: -fmodule-map-file=<file>
+
+Load this module map file
+
+.. option:: -fmodule-name=<name>, -fmodule-implementation-of <arg>, -fmodule-name <arg>
+
+Specify the name of the module to build
+
+.. option:: -fmodules, -fno-modules
+
+Enable the 'modules' language feature
+
+.. option:: -fmodules-decluse, -fno-modules-decluse
+
+Require declaration of modules used within a module
+
+.. option:: -fmodules-ignore-macro=<arg>
+
+Ignore the definition of the given macro when building and loading modules
+
+.. option:: -fmodules-search-all, -fno-modules-search-all
+
+Search even non-imported modules to resolve references
+
+.. option:: -fmodules-strict-decluse
+
+Like -fmodules-decluse but requires all headers to be in modules
+
+.. option:: -fmodules-ts
+
+Enable support for the C++ Modules TS
+
+.. option:: -fms-compatibility, -fno-ms-compatibility
+
+Enable full Microsoft Visual C++ compatibility
+
+.. option:: -fms-compatibility-version=<arg>
+
+Dot-separated value representing the Microsoft compiler version number to report in \_MSC\_VER (0 = don't define it (default))
+
+.. option:: -fms-extensions, -fno-ms-extensions
+
+Accept some non-standard constructs supported by the Microsoft compiler
+
+.. option:: -fms-memptr-rep=<arg>
+
+.. option:: -fms-volatile<arg>
+
+.. option:: -fmsc-version=<arg>
+
+Microsoft compiler version number to report in \_MSC\_VER (0 = don't define it (default))
+
+.. option:: -fmudflap
+
+.. option:: -fmudflapth
+
+.. option:: -fnested-functions
+
+.. option:: -fnew-alignment=<align>, -fnew-alignment <arg>
+
+Specifies the largest alignment guaranteed by '::operator new(size\_t)'
+
+.. option:: -fnext-runtime
+
+.. option:: -fno-builtin-<arg>
+
+Disable implicit builtin knowledge of a specific function
+
+.. option:: -fno-elide-type
+
+Do not elide types when printing diagnostics
+
+.. option:: -fno-max-type-align
+
+.. option:: -fno-operator-names
+
+Do not treat C++ operator name keywords as synonyms for operators
+
+.. option:: -fno-rtti-data
+
+Control emission of RTTI data
+
+.. option:: -fno-strict-modules-decluse
+
+.. option:: -fno-working-directory
+
+.. option:: -fnoxray-link-deps
+
+.. option:: -fobjc-abi-version=<arg>
+
+.. option:: -fobjc-arc, -fno-objc-arc
+
+Synthesize retain and release calls for Objective-C pointers
+
+.. option:: -fobjc-arc-exceptions, -fno-objc-arc-exceptions
+
+Use EH-safe code when synthesizing retains and releases in -fobjc-arc
+
+.. option:: -fobjc-exceptions, -fno-objc-exceptions
+
+Enable Objective-C exceptions
+
+.. option:: -fobjc-infer-related-result-type, -fno-objc-infer-related-result-type
+
+.. option:: -fobjc-legacy-dispatch, -fno-objc-legacy-dispatch
+
+.. option:: -fobjc-link-runtime
+
+.. option:: -fobjc-nonfragile-abi, -fno-objc-nonfragile-abi
+
+.. option:: -fobjc-nonfragile-abi-version=<arg>
+
+.. option:: -fobjc-runtime=<arg>
+
+Specify the target Objective-C runtime kind and version
+
+.. option:: -fobjc-sender-dependent-dispatch
+
+.. option:: -fobjc-weak, -fno-objc-weak
+
+Enable ARC-style weak references in Objective-C
+
+.. option:: -fomit-frame-pointer, -fno-omit-frame-pointer
+
+.. option:: -fopenmp, -fno-openmp
+
+Parse OpenMP pragmas and generate parallel code.
+
+.. option:: -fopenmp-simd, -fno-openmp-simd
+
+Emit OpenMP code only for SIMD-based constructs.
+
+.. option:: -fopenmp-version=<arg>
+
+.. program:: clang1
+.. option:: -fopenmp=<arg>
+.. program:: clang
+
+.. option:: -foperator-arrow-depth=<arg>
+
+.. option:: -foptimization-record-file=<arg>
+
+Specify the file name of any generated YAML optimization record
+
+.. option:: -foptimize-sibling-calls, -fno-optimize-sibling-calls
+
+.. option:: -foutput-class-dir=<arg>, --output-class-directory <arg>, --output-class-directory=<arg>
+
+.. option:: -fpack-struct, -fno-pack-struct
+
+.. program:: clang1
+.. option:: -fpack-struct=<arg>
+.. program:: clang
+
+Specify the default maximum struct packing alignment
+
+.. option:: -fpascal-strings, -fno-pascal-strings, -mpascal-strings
+
+Recognize and construct Pascal-style string literals
+
+.. option:: -fpcc-struct-return
+
+Override the default ABI to return all structs on the stack
+
+.. option:: -fpch-preprocess
+
+.. option:: -fpic, -fno-pic
+
+.. option:: -fpie, -fno-pie
+
+.. option:: -fplt, -fno-plt
+
+Use the PLT to make function calls
+
+.. option:: -fplugin=<dsopath>
+
+Load the named plugin (dynamic shared object)
+
+.. option:: -fpreserve-as-comments, -fno-preserve-as-comments
+
+.. option:: -fprofile-arcs, -fno-profile-arcs
+
+.. option:: -fprofile-dir=<arg>
+
+.. option:: -fprofile-generate, -fno-profile-generate
+
+Generate instrumented code to collect execution counts into default.profraw (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. program:: clang1
+.. option:: -fprofile-generate=<directory>
+.. program:: clang
+
+Generate instrumented code to collect execution counts into <directory>/default.profraw (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. option:: -fprofile-instr-generate, -fno-profile-instr-generate
+
+Generate instrumented code to collect execution counts into default.profraw file (overridden by '=' form of option or LLVM\_PROFILE\_FILE env var)
+
+.. program:: clang1
+.. option:: -fprofile-instr-generate=<file>
+.. program:: clang
+
+Generate instrumented code to collect execution counts into <file> (overridden by LLVM\_PROFILE\_FILE env var)
+
+.. option:: -fprofile-instr-use, -fno-profile-instr-use, -fprofile-use
+
+.. program:: clang1
+.. option:: -fprofile-instr-use=<arg>
+.. program:: clang
+
+Use instrumentation data for profile-guided optimization
+
+.. option:: -fprofile-sample-accurate, -fauto-profile-accurate, -fno-profile-sample-accurate
+
+Specifies that the sample profile is accurate. If the sample
+               profile is accurate, callsites without profile samples are marked
+               as cold. Otherwise, treat callsites without profile samples as if
+               we have no profile
+
+.. option:: -fprofile-sample-use, -fauto-profile, -fno-profile-sample-use
+
+.. program:: clang1
+.. option:: -fprofile-sample-use=<arg>, -fauto-profile=<arg>
+.. program:: clang
+
+Enable sample-based profile guided optimizations
+
+.. program:: clang1
+.. option:: -fprofile-use=<pathname>
+.. program:: clang
+
+Use instrumentation data for profile-guided optimization. If pathname is a directory, it reads from <pathname>/default.profdata. Otherwise, it reads from file <pathname>.
+
+.. option:: -freciprocal-math, -fno-reciprocal-math
+
+Allow division operations to be reassociated
+
+.. option:: -freg-struct-return
+
+Override the default ABI to return small structs in registers
+
+.. option:: -fregister-global-dtors-with-atexit, -fno-register-global-dtors-with-atexit
+
+Use atexit or \_\_cxa\_atexit to register global destructors
+
+.. option:: -frelaxed-template-template-args, -fno-relaxed-template-template-args
+
+Enable C++17 relaxed template template argument matching
+
+.. option:: -freroll-loops, -fno-reroll-loops
+
+Turn on loop reroller
+
+.. option:: -fretain-comments-from-system-headers
+
+.. option:: -frewrite-imports, -fno-rewrite-imports
+
+.. option:: -frewrite-includes, -fno-rewrite-includes
+
+.. option:: -frewrite-map-file <arg>
+
+.. program:: clang1
+.. option:: -frewrite-map-file=<arg>
+.. program:: clang
+
+.. option:: -fropi, -fno-ropi
+
+.. option:: -frtti, -fno-rtti
+
+.. option:: -frwpi, -fno-rwpi
+
+.. option:: -fsave-optimization-record, -fno-save-optimization-record
+
+Generate a YAML optimization record file
+
+.. option:: -fseh-exceptions
+
+Use SEH style exceptions
+
+.. option:: -fshort-enums, -fno-short-enums
+
+Allocate to an enum type only as many bytes as it needs for the declared range of possible values
+
+.. option:: -fshort-wchar, -fno-short-wchar
+
+Force wchar\_t to be a short unsigned int
+
+.. option:: -fshow-column, -fno-show-column
+
+.. option:: -fshow-overloads=<arg>
+
+Which overload candidates to show when overload resolution fails: best\|all; defaults to all
+
+.. option:: -fshow-source-location, -fno-show-source-location
+
+.. option:: -fsignaling-math, -fno-signaling-math
+
+.. option:: -fsigned-bitfields
+
+.. option:: -fsigned-char, -fno-signed-char, --signed-char
+
+.. option:: -fsigned-zeros, -fno-signed-zeros
+
+.. option:: -fsized-deallocation, -fno-sized-deallocation
+
+Enable C++14 sized global deallocation functions
+
+.. option:: -fsjlj-exceptions
+
+Use SjLj style exceptions
+
+.. option:: -fslp-vectorize, -fno-slp-vectorize, -ftree-slp-vectorize
+
+Enable the superword-level parallelism vectorization passes
+
+.. option:: -fspell-checking, -fno-spell-checking
+
+.. option:: -fspell-checking-limit=<arg>
+
+.. option:: -fsplit-dwarf-inlining, -fno-split-dwarf-inlining
+
+Provide minimal debug info in the object/executable to facilitate online symbolication/stack traces in the absence of .dwo/.dwp files when using Split DWARF
+
+.. option:: -fsplit-stack
+
+.. option:: -fstack-protector, -fno-stack-protector
+
+Enable stack protectors for functions potentially vulnerable to stack smashing
+
+.. option:: -fstack-protector-all
+
+Force the usage of stack protectors for all functions
+
+.. option:: -fstack-protector-strong
+
+Use a strong heuristic to apply stack protectors to functions
+
+.. option:: -fstack-size-section, -fno-stack-size-section
+
+Emit section containing metadata on function stack sizes
+
+.. option:: -fstandalone-debug, -fno-limit-debug-info, -fno-standalone-debug
+
+Emit full debug info for all types used by the program
+
+.. option:: -fstrict-aliasing, -fno-strict-aliasing
+
+.. option:: -fstrict-enums, -fno-strict-enums
+
+Enable optimizations based on the strict definition of an enum's value range
+
+.. option:: -fstrict-float-cast-overflow, -fno-strict-float-cast-overflow
+
+Assume that overflowing float-to-int casts are undefined (default)
+
+.. option:: -fstrict-overflow, -fno-strict-overflow
+
+.. option:: -fstrict-return, -fno-strict-return
+
+Always treat control flow paths that fall off the end of a non-void function as unreachable
+
+.. option:: -fstrict-vtable-pointers, -fno-strict-vtable-pointers
+
+Enable optimizations based on the strict rules for overwriting polymorphic C++ objects
+
+.. option:: -fstruct-path-tbaa, -fno-struct-path-tbaa
+
+.. option:: -ftabstop=<arg>
+
+.. option:: -ftemplate-backtrace-limit=<arg>
+
+.. option:: -ftemplate-depth-<arg>
+
+.. option:: -ftemplate-depth=<arg>
+
+.. option:: -ftest-coverage
+
+.. option:: -fthinlto-index=<arg>
+
+Perform ThinLTO importing using provided function summary index
+
+.. option:: -fthreadsafe-statics, -fno-threadsafe-statics
+
+.. option:: -ftime-report
+
+.. option:: -ftls-model=<arg>
+
+.. option:: -ftrap-function=<arg>
+
+Issue call to specified function rather than a trap instruction
+
+.. option:: -ftrapping-math, -fno-trapping-math
+
+.. option:: -ftrapv
+
+Trap on integer overflow
+
+.. option:: -ftrapv-handler <arg>
+
+.. program:: clang1
+.. option:: -ftrapv-handler=<function name>
+.. program:: clang
+
+Specify the function to be called on overflow
+
+.. option:: -ftrigraphs, -fno-trigraphs, -trigraphs, --trigraphs
+
+Process trigraph sequences
+
+.. option:: -funique-section-names, -fno-unique-section-names
+
+Use unique names for text and data sections (ELF Only)
+
+.. option:: -funit-at-a-time, -fno-unit-at-a-time
+
+.. option:: -funroll-loops, -fno-unroll-loops
+
+Turn on loop unroller
+
+.. option:: -funsafe-math-optimizations, -fno-unsafe-math-optimizations
+
+.. option:: -funsigned-bitfields
+
+.. option:: -funsigned-char, -fno-unsigned-char, --unsigned-char
+
+.. option:: -funwind-tables, -fno-unwind-tables
+
+.. option:: -fuse-cxa-atexit, -fno-use-cxa-atexit
+
+.. option:: -fuse-init-array, -fno-use-init-array
+
+Use .init\_array instead of .ctors
+
+.. option:: -fuse-ld=<arg>
+
+.. option:: -fuse-line-directives, -fno-use-line-directives
+
+.. option:: -fveclib=<arg>
+
+Use the given vector functions library
+
+.. option:: -fvectorize, -fno-vectorize, -ftree-vectorize
+
+Enable the loop vectorization passes
+
+.. option:: -fverbose-asm, -fno-verbose-asm
+
+.. option:: -fvisibility-inlines-hidden
+
+Give inline C++ member functions hidden visibility by default
+
+.. option:: -fvisibility-ms-compat
+
+Give global types 'default' visibility and global functions and variables 'hidden' visibility by default
+
+.. option:: -fvisibility=<arg>
+
+Set the default symbol visibility for all global declarations
+
+.. option:: -fwhole-program-vtables, -fno-whole-program-vtables
+
+Enables whole-program vtable optimization. Requires -flto
+
+.. option:: -fwrapv, -fno-wrapv
+
+Treat signed integer overflow as two's complement
+
+.. option:: -fwritable-strings
+
+Store string literals as writable data
+
+.. option:: -fxray-always-emit-customevents, -fno-xray-always-emit-customevents
+
+Determine whether to always emit \_\_xray\_customevent(...) calls even if the function it appears in is not always instrumented.
+
+.. option:: -fxray-always-emit-typedevents, -fno-xray-always-emit-typedevents
+
+Determine whether to always emit \_\_xray\_typedevent(...) calls even if the function it appears in is not always instrumented.
+
+.. option:: -fxray-always-instrument=<arg>
+
+DEPRECATED: Filename defining the whitelist for imbuing the 'always instrument' XRay attribute.
+
+.. option:: -fxray-attr-list=<arg>
+
+Filename defining the list of functions/types for imbuing XRay attributes.
+
+.. option:: -fxray-instruction-threshold<arg>
+
+.. program:: clang1
+.. option:: -fxray-instruction-threshold=<arg>
+.. program:: clang
+
+Sets the minimum function size to instrument with XRay
+
+.. option:: -fxray-instrument, -fno-xray-instrument
+
+Generate XRay instrumentation sleds on function entry and exit
+
+.. option:: -fxray-instrumentation-bundle=<arg>
+
+Select which XRay instrumentation points to emit. Options: all, none, function, custom. Default is 'all'.
+
+.. option:: -fxray-link-deps
+
+Tells clang to add the link dependencies for XRay.
+
+.. option:: -fxray-modes=<arg>
+
+List of modes to link in by default into XRay instrumented binaries.
+
+.. option:: -fxray-never-instrument=<arg>
+
+DEPRECATED: Filename defining the whitelist for imbuing the 'never instrument' XRay attribute.
+
+.. option:: -fzero-initialized-in-bss, -fno-zero-initialized-in-bss
+
+.. option:: -fzvector, -fno-zvector, -mzvector
+
+Enable System z vector language extension
+
+.. option:: -pedantic, --pedantic, -no-pedantic, --no-pedantic
+
+.. option:: -pedantic-errors, --pedantic-errors
+
+OpenCL flags
+------------
+.. option:: -cl-denorms-are-zero
+
+OpenCL only. Allow denormals to be flushed to zero.
+
+.. option:: -cl-fast-relaxed-math
+
+OpenCL only. Sets -cl-finite-math-only and -cl-unsafe-math-optimizations, and defines \_\_FAST\_RELAXED\_MATH\_\_.
+
+.. option:: -cl-finite-math-only
+
+OpenCL only. Allow floating-point optimizations that assume arguments and results are not NaNs or +-Inf.
+
+.. option:: -cl-fp32-correctly-rounded-divide-sqrt
+
+OpenCL only. Specify that single precision floating-point divide and sqrt used in the program source are correctly rounded.
+
+.. option:: -cl-kernel-arg-info
+
+OpenCL only. Generate kernel argument metadata.
+
+.. option:: -cl-mad-enable
+
+OpenCL only. Allow use of less precise MAD computations in the generated binary.
+
+.. option:: -cl-no-signed-zeros
+
+OpenCL only. Allow use of less precise no signed zeros computations in the generated binary.
+
+.. option:: -cl-opt-disable
+
+OpenCL only. This option disables all optimizations. By default optimizations are enabled.
+
+.. option:: -cl-single-precision-constant
+
+OpenCL only. Treat double precision floating-point constant as single precision constant.
+
+.. option:: -cl-std=<arg>
+
+OpenCL language standard to compile for.
+
+.. option:: -cl-strict-aliasing
+
+OpenCL only. This option is added for compatibility with OpenCL 1.0.
+
+.. option:: -cl-uniform-work-group-size
+
+OpenCL only. Defines that the global work-size be a multiple of the work-group size specified to clEnqueueNDRangeKernel
+
+.. option:: -cl-unsafe-math-optimizations
+
+OpenCL only. Allow unsafe floating-point optimizations.  Also implies -cl-no-signed-zeros and -cl-mad-enable.
+
+Target-dependent compilation options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. option:: -G<size>, -G=<arg>, -msmall-data-threshold=<arg>
+
+Put objects of at most <size> bytes into small data section (MIPS / Hexagon)
+
+.. option:: -m16
+
+.. option:: -m32
+
+.. option:: -m64
+
+.. option:: -mabi=<arg>
+
+.. option:: -malign-double
+
+Align doubles to two words in structs (x86 only)
+
+.. option:: -march=<arg>
+
+.. option:: -masm=<arg>
+
+.. option:: -mbackchain, -mno-backchain
+
+Link stack frames through backchain on System Z
+
+.. option:: -mcmodel=<arg>
+
+.. option:: -mconsole<arg>
+
+.. option:: -mcpu=<arg>, -mv4 (equivalent to -mcpu=hexagonv4), -mv5 (equivalent to -mcpu=hexagonv5), -mv55 (equivalent to -mcpu=hexagonv55), -mv60 (equivalent to -mcpu=hexagonv60), -mv62 (equivalent to -mcpu=hexagonv62), -mv65 (equivalent to -mcpu=hexagonv65)
+
+.. option:: -mcrc, -mno-crc
+
+Allow use of CRC instructions (ARM/Mips only)
+
+.. option:: -mdefault-build-attributes<arg>, -mno-default-build-attributes<arg>
+
+.. option:: -mdll<arg>
+
+.. option:: -mdynamic-no-pic<arg>
+
+.. option:: -meabi <arg>
+
+Set EABI type, e.g. 4, 5 or gnu (default depends on triple)
+
+.. option:: -mfentry
+
+Insert calls to fentry at function entry (x86 only)
+
+.. option:: -mfloat-abi=<arg>
+
+.. option:: -mfpmath=<arg>
+
+.. option:: -mfpu=<arg>
+
+.. option:: -mglobal-merge, -mno-global-merge
+
+Enable merging of globals
+
+.. option:: -mhard-float
+
+.. option:: -mhwdiv=<arg>, --mhwdiv <arg>, --mhwdiv=<arg>
+
+.. option:: -miamcu, -mno-iamcu
+
+Use Intel MCU ABI
+
+.. option:: -mimplicit-float, -mno-implicit-float
+
+.. option:: -mimplicit-it=<arg>
+
+.. option:: -mincremental-linker-compatible, -mno-incremental-linker-compatible
+
+(integrated-as) Emit an object file which can be used with an incremental linker
+
+.. option:: -miphoneos-version-min=<arg>, -mios-version-min=<arg>
+
+.. option:: -mkernel
+
+.. option:: -mlong-calls, -mno-long-calls
+
+Generate branches with extended addressability, usually via indirect jumps.
+
+.. option:: -mmacosx-version-min=<arg>, -mmacos-version-min=<arg>
+
+Set Mac OS X deployment target
+
+.. option:: -mmcu=<arg>
+
+.. option:: -mms-bitfields, -mno-ms-bitfields
+
+Set the default structure layout to be compatible with the Microsoft compiler standard
+
+.. option:: -momit-leaf-frame-pointer, -mno-omit-leaf-frame-pointer
+
+Omit frame pointer setup for leaf functions
+
+.. option:: -moslib=<arg>
+
+.. option:: -mpie-copy-relocations, -mno-pie-copy-relocations
+
+Use copy relocations support for PIE builds
+
+.. option:: -mprefer-vector-width=<arg>
+
+Specifies preferred vector width for auto-vectorization. Defaults to 'none' which allows target specific decisions.
+
+.. option:: -mqdsp6-compat
+
+Enable hexagon-qdsp6 backward compatibility
+
+.. option:: -mrecip
+
+.. program:: clang1
+.. option:: -mrecip=<arg1>,<arg2>...
+.. program:: clang
+
+.. option:: -mred-zone, -mno-red-zone
+
+.. option:: -mregparm=<arg>
+
+.. option:: -mrelax-all, -mno-relax-all
+
+(integrated-as) Relax all machine instructions
+
+.. option:: -mrtd, -mno-rtd
+
+Make StdCall calling convention the default
+
+.. option:: -msoft-float, -mno-soft-float
+
+Use software floating point
+
+.. option:: -mstack-alignment=<arg>
+
+Set the stack alignment
+
+.. option:: -mstack-arg-probe, -mno-stack-arg-probe
+
+Enable stack probes
+
+.. option:: -mstack-probe-size=<arg>
+
+Set the stack probe size
+
+.. option:: -mstackrealign, -mno-stackrealign
+
+Force realign the stack at entry to every function
+
+.. option:: -mthread-model <arg>
+
+The thread model to use, e.g. posix, single (posix by default)
+
+.. option:: -mthreads<arg>
+
+.. option:: -mthumb, -mno-thumb
+
+.. option:: -mtune=<arg>
+
+.. option:: -mtvos-version-min=<arg>, -mappletvos-version-min=<arg>
+
+.. option:: -municode<arg>
+
+.. option:: -mvx, -mno-vx
+
+.. option:: -mwarn-nonportable-cfstrings, -mno-warn-nonportable-cfstrings
+
+.. option:: -mwatchos-version-min=<arg>
+
+.. option:: -mwindows<arg>
+
+.. option:: -mx32
+
+AARCH64
+-------
+.. option:: -ffixed-x18
+
+Reserve the x18 register (AArch64 only)
+
+.. option:: -ffixed-x20
+
+Reserve the x20 register (AArch64 only)
+
+.. option:: -mfix-cortex-a53-835769, -mno-fix-cortex-a53-835769
+
+Workaround Cortex-A53 erratum 835769 (AArch64 only)
+
+.. option:: -mgeneral-regs-only
+
+Generate code which only uses the general purpose registers (AArch64 only)
+
+AMDGPU
+------
+.. option:: -mxnack, -mno-xnack
+
+Enable XNACK (AMDGPU only)
+
+ARM
+---
+.. option:: -ffixed-r9
+
+Reserve the r9 register (ARM only)
+
+.. option:: -mexecute-only, -mno-execute-only, -mpure-code
+
+Disallow generation of data access to code sections (ARM only)
+
+.. option:: -mno-movt
+
+Disallow use of movt/movw pairs (ARM only)
+
+.. option:: -mno-neg-immediates
+
+Disallow converting instructions with negative immediates to their negation or inversion.
+
+.. option:: -mnocrc
+
+Disallow use of CRC instructions (ARM only)
+
+.. option:: -mrestrict-it, -mno-restrict-it
+
+Disallow generation of deprecated IT blocks for ARMv8. It is on by default for ARMv8 Thumb mode.
+
+.. option:: -mtp=<arg>
+
+Read thread pointer from coprocessor register (ARM only)
+
+.. option:: -munaligned-access, -mno-unaligned-access
+
+Allow memory accesses to be unaligned (AArch32/AArch64 only)
+
+Hexagon
+-------
+.. option:: -mieee-rnd-near
+
+.. option:: -mmemops, -mno-memops
+
+Enable generation of memop instructions
+
+.. option:: -mnvj, -mno-nvj
+
+Enable generation of new-value jumps
+
+.. option:: -mnvs, -mno-nvs
+
+Enable generation of new-value stores
+
+.. option:: -mpackets, -mno-packets
+
+Enable generation of instruction packets
+
+Hexagon
+-------
+.. option:: -mhvx, -mno-hvx
+
+Enable Hexagon Vector eXtensions
+
+.. option:: -mhvx-length=<arg>
+
+Set Hexagon Vector Length
+
+.. program:: clang1
+.. option:: -mhvx=<arg>
+.. program:: clang
+
+Enable Hexagon Vector eXtensions
+
+MIPS
+----
+.. option:: -mabicalls, -mno-abicalls
+
+Enable SVR4-style position-independent code (Mips only)
+
+.. option:: -mabs=<arg>
+
+.. option:: -mcheck-zero-division, -mno-check-zero-division
+
+.. option:: -mcompact-branches=<arg>
+
+.. option:: -mdouble-float
+
+.. option:: -mdsp, -mno-dsp
+
+.. option:: -mdspr2, -mno-dspr2
+
+.. option:: -membedded-data, -mno-embedded-data
+
+Place constants in the .rodata section instead of the .sdata section even if they meet the -G <size> threshold (MIPS)
+
+.. option:: -mextern-sdata, -mno-extern-sdata
+
+Assume that externally defined data is in the small data if it meets the -G <size> threshold (MIPS)
+
+.. option:: -mfp32
+
+Use 32-bit floating point registers (MIPS only)
+
+.. option:: -mfp64
+
+Use 64-bit floating point registers (MIPS only)
+
+.. option:: -mginv, -mno-ginv
+
+.. option:: -mgpopt, -mno-gpopt
+
+Use GP relative accesses for symbols known to be in a small data section (MIPS)
+
+.. option:: -mindirect-jump=<arg>
+
+Change indirect jump instructions to inhibit speculation
+
+.. option:: -mips16
+
+.. option:: -mldc1-sdc1, -mno-ldc1-sdc1
+
+.. option:: -mlocal-sdata, -mno-local-sdata
+
+Extend the -G behaviour to object local data (MIPS)
+
+.. option:: -mmadd4, -mno-madd4
+
+Enable the generation of 4-operand madd.s, madd.d and related instructions.
+
+.. option:: -mmicromips, -mno-micromips
+
+.. option:: -mmsa, -mno-msa
+
+Enable MSA ASE (MIPS only)
+
+.. option:: -mmt, -mno-mt
+
+Enable MT ASE (MIPS only)
+
+.. option:: -mnan=<arg>
+
+.. option:: -mno-mips16
+
+.. option:: -msingle-float
+
+.. option:: -mvirt, -mno-virt
+
+.. option:: -mxgot, -mno-xgot
+
+PowerPC
+-------
+.. option:: -maltivec, -mno-altivec
+
+.. option:: -mcmpb, -mno-cmpb
+
+.. option:: -mcrbits, -mno-crbits
+
+.. option:: -mcrypto, -mno-crypto
+
+.. option:: -mdirect-move, -mno-direct-move
+
+.. option:: -mfloat128, -mno-float128
+
+.. option:: -mfprnd, -mno-fprnd
+
+.. option:: -mhtm, -mno-htm
+
+.. option:: -minvariant-function-descriptors, -mno-invariant-function-descriptors
+
+.. option:: -misel, -mno-isel
+
+.. option:: -mlongcall, -mno-longcall
+
+.. option:: -mmfocrf, -mmfcrf, -mno-mfocrf
+
+.. option:: -mpopcntd, -mno-popcntd
+
+.. option:: -mpower8-vector, -mno-power8-vector
+
+.. option:: -mpower9-vector, -mno-power9-vector
+
+.. option:: -mqpx, -mno-qpx
+
+.. option:: -msecure-plt
+
+.. option:: -mvsx, -mno-vsx
+
+WebAssembly
+-----------
+.. option:: -mexception-handling, -mno-exception-handling
+
+.. option:: -mnontrapping-fptoint, -mno-nontrapping-fptoint
+
+.. option:: -msign-ext, -mno-sign-ext
+
+.. option:: -msimd128, -mno-simd128
+
+X86
+---
+.. option:: -m3dnow, -mno-3dnow
+
+.. option:: -m3dnowa, -mno-3dnowa
+
+.. option:: -madx, -mno-adx
+
+.. option:: -maes, -mno-aes
+
+.. option:: -mavx, -mno-avx
+
+.. option:: -mavx2, -mno-avx2
+
+.. option:: -mavx512bitalg, -mno-avx512bitalg
+
+.. option:: -mavx512bw, -mno-avx512bw
+
+.. option:: -mavx512cd, -mno-avx512cd
+
+.. option:: -mavx512dq, -mno-avx512dq
+
+.. option:: -mavx512er, -mno-avx512er
+
+.. option:: -mavx512f, -mno-avx512f
+
+.. option:: -mavx512ifma, -mno-avx512ifma
+
+.. option:: -mavx512pf, -mno-avx512pf
+
+.. option:: -mavx512vbmi, -mno-avx512vbmi
+
+.. option:: -mavx512vbmi2, -mno-avx512vbmi2
+
+.. option:: -mavx512vl, -mno-avx512vl
+
+.. option:: -mavx512vnni, -mno-avx512vnni
+
+.. option:: -mavx512vpopcntdq, -mno-avx512vpopcntdq
+
+.. option:: -mbmi, -mno-bmi
+
+.. option:: -mbmi2, -mno-bmi2
+
+.. option:: -mcldemote, -mno-cldemote
+
+.. option:: -mclflushopt, -mno-clflushopt
+
+.. option:: -mclwb, -mno-clwb
+
+.. option:: -mclzero, -mno-clzero
+
+.. option:: -mcx16, -mno-cx16
+
+.. option:: -mf16c, -mno-f16c
+
+.. option:: -mfma, -mno-fma
+
+.. option:: -mfma4, -mno-fma4
+
+.. option:: -mfsgsbase, -mno-fsgsbase
+
+.. option:: -mfxsr, -mno-fxsr
+
+.. option:: -mgfni, -mno-gfni
+
+.. option:: -minvpcid, -mno-invpcid
+
+.. option:: -mlwp, -mno-lwp
+
+.. option:: -mlzcnt, -mno-lzcnt
+
+.. option:: -mmmx, -mno-mmx
+
+.. option:: -mmovbe, -mno-movbe
+
+.. option:: -mmovdir64b, -mno-movdir64b
+
+.. option:: -mmovdiri, -mno-movdiri
+
+.. option:: -mmpx, -mno-mpx
+
+.. option:: -mmwaitx, -mno-mwaitx
+
+.. option:: -mpclmul, -mno-pclmul
+
+.. option:: -mpconfig, -mno-pconfig
+
+.. option:: -mpku, -mno-pku
+
+.. option:: -mpopcnt, -mno-popcnt
+
+.. option:: -mprefetchwt1, -mno-prefetchwt1
+
+.. option:: -mprfchw, -mno-prfchw
+
+.. option:: -mptwrite, -mno-ptwrite
+
+.. option:: -mrdpid, -mno-rdpid
+
+.. option:: -mrdrnd, -mno-rdrnd
+
+.. option:: -mrdseed, -mno-rdseed
+
+.. option:: -mretpoline, -mno-retpoline
+
+.. option:: -mretpoline-external-thunk, -mno-retpoline-external-thunk
+
+.. option:: -mrtm, -mno-rtm
+
+.. option:: -msahf, -mno-sahf
+
+.. option:: -msgx, -mno-sgx
+
+.. option:: -msha, -mno-sha
+
+.. option:: -mshstk, -mno-shstk
+
+.. option:: -msse, -mno-sse
+
+.. option:: -msse2, -mno-sse2
+
+.. option:: -msse3, -mno-sse3
+
+.. option:: -msse4.1, -mno-sse4.1
+
+.. program:: clang1
+.. option:: -msse4.2, -mno-sse4.2, -msse4
+.. program:: clang
+
+.. option:: -msse4a, -mno-sse4a
+
+.. option:: -mssse3, -mno-ssse3
+
+.. option:: -mtbm, -mno-tbm
+
+.. option:: -mvaes, -mno-vaes
+
+.. option:: -mvpclmulqdq, -mno-vpclmulqdq
+
+.. option:: -mwaitpkg, -mno-waitpkg
+
+.. option:: -mwbnoinvd, -mno-wbnoinvd
+
+.. option:: -mx87, -m80387, -mno-x87
+
+.. option:: -mxop, -mno-xop
+
+.. option:: -mxsave, -mno-xsave
+
+.. option:: -mxsavec, -mno-xsavec
+
+.. option:: -mxsaveopt, -mno-xsaveopt
+
+.. option:: -mxsaves, -mno-xsaves
+
+RISCV
+-----
+.. option:: -mrelax, -mno-relax
+
+Enable linker relaxation
+
+Optimization level
+~~~~~~~~~~~~~~~~~~
+
+Flags controlling how much optimization should be performed.
+
+.. option:: -O<arg>, -O (equivalent to -O2), --optimize, --optimize=<arg>
+
+.. option:: -Ofast<arg>
+
+Debug information generation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Flags controlling how much and what kind of debug information should be
+generated.
+
+Kind and level of debug information
+-----------------------------------
+.. option:: -g, --debug, --debug=<arg>
+
+Generate source-level debug information
+
+.. option:: -gdwarf-2
+
+Generate source-level debug information with dwarf version 2
+
+.. option:: -gdwarf-3
+
+Generate source-level debug information with dwarf version 3
+
+.. option:: -gdwarf-4, -gdwarf
+
+Generate source-level debug information with dwarf version 4
+
+.. option:: -gdwarf-5
+
+Generate source-level debug information with dwarf version 5
+
+.. option:: -gfull
+
+.. option:: -gused
+
+Debug level
+___________
+.. option:: -g0
+
+.. option:: -g2
+
+.. option:: -g3
+
+.. option:: -ggdb0
+
+.. option:: -ggdb1
+
+.. option:: -ggdb2
+
+.. option:: -ggdb3
+
+.. option:: -gline-tables-only, -g1, -gmlt
+
+Emit debug line number tables only
+
+.. option:: -gmodules
+
+Generate debug info with external references to clang modules or precompiled headers
+
+Debugger to tune debug information for
+______________________________________
+.. option:: -ggdb
+
+.. option:: -glldb
+
+.. option:: -gsce
+
+Debug information flags
+-----------------------
+.. option:: -gcolumn-info, -gno-column-info
+
+.. option:: -gdwarf-aranges
+
+.. option:: -gembed-source, -gno-embed-source
+
+Embed source text in DWARF debug sections
+
+.. option:: -ggnu-pubnames, -gno-gnu-pubnames
+
+.. option:: -grecord-gcc-switches, -gno-record-gcc-switches
+
+.. option:: -gsplit-dwarf
+
+.. option:: -gstrict-dwarf, -gno-strict-dwarf
+
+.. option:: -gz
+
+DWARF debug sections compression type
+
+.. program:: clang1
+.. option:: -gz=<arg>
+.. program:: clang
+
+DWARF debug sections compression type
+
+Static analyzer flags
+=====================
+
+Flags controlling the behavior of the Clang Static Analyzer.
+
+.. option:: -Xanalyzer <arg>
+
+Pass <arg> to the static analyzer
+
+Fortran compilation flags
+=========================
+
+Flags that will be passed onto the ``gfortran`` compiler when Clang is given
+a Fortran input.
+
+.. option:: -A<arg>, --assert <arg>, --assert=<arg>
+
+.. option:: -A-<arg>
+
+.. option:: -J<arg>
+
+.. option:: -cpp
+
+.. option:: -faggressive-function-elimination, -fno-aggressive-function-elimination
+
+.. option:: -falign-commons, -fno-align-commons
+
+.. option:: -fall-intrinsics, -fno-all-intrinsics
+
+.. option:: -fautomatic, -fno-automatic
+
+.. option:: -fbackslash, -fno-backslash
+
+.. option:: -fbacktrace, -fno-backtrace
+
+.. option:: -fblas-matmul-limit=<arg>
+
+.. option:: -fbounds-check, -fno-bounds-check
+
+.. option:: -fcheck-array-temporaries, -fno-check-array-temporaries
+
+.. option:: -fcheck=<arg>
+
+.. option:: -fcoarray=<arg>
+
+.. option:: -fconvert=<arg>
+
+.. option:: -fcray-pointer, -fno-cray-pointer
+
+.. option:: -fd-lines-as-code, -fno-d-lines-as-code
+
+.. option:: -fd-lines-as-comments, -fno-d-lines-as-comments
+
+.. option:: -fdefault-double-8, -fno-default-double-8
+
+.. option:: -fdefault-integer-8, -fno-default-integer-8
+
+.. option:: -fdefault-real-8, -fno-default-real-8
+
+.. option:: -fdollar-ok, -fno-dollar-ok
+
+.. option:: -fdump-fortran-optimized, -fno-dump-fortran-optimized
+
+.. option:: -fdump-fortran-original, -fno-dump-fortran-original
+
+.. option:: -fdump-parse-tree, -fno-dump-parse-tree
+
+.. option:: -fexternal-blas, -fno-external-blas
+
+.. option:: -ff2c, -fno-f2c
+
+.. option:: -ffixed-form, -fno-fixed-form
+
+.. option:: -ffixed-line-length-<arg>
+
+.. option:: -ffpe-trap=<arg>
+
+.. option:: -ffree-form, -fno-free-form
+
+.. option:: -ffree-line-length-<arg>
+
+.. option:: -ffrontend-optimize, -fno-frontend-optimize
+
+.. option:: -fimplicit-none, -fno-implicit-none
+
+.. option:: -finit-character=<arg>
+
+.. option:: -finit-integer=<arg>
+
+.. option:: -finit-local-zero, -fno-init-local-zero
+
+.. option:: -finit-logical=<arg>
+
+.. option:: -finit-real=<arg>
+
+.. option:: -finteger-4-integer-8, -fno-integer-4-integer-8
+
+.. option:: -fintrinsic-modules-path, -fno-intrinsic-modules-path
+
+.. option:: -fmax-array-constructor=<arg>
+
+.. option:: -fmax-errors=<arg>
+
+.. option:: -fmax-identifier-length, -fno-max-identifier-length
+
+.. option:: -fmax-stack-var-size=<arg>
+
+.. option:: -fmax-subrecord-length=<arg>
+
+.. option:: -fmodule-private, -fno-module-private
+
+.. option:: -fpack-derived, -fno-pack-derived
+
+.. option:: -fprotect-parens, -fno-protect-parens
+
+.. option:: -frange-check, -fno-range-check
+
+.. option:: -freal-4-real-10, -fno-real-4-real-10
+
+.. option:: -freal-4-real-16, -fno-real-4-real-16
+
+.. option:: -freal-4-real-8, -fno-real-4-real-8
+
+.. option:: -freal-8-real-10, -fno-real-8-real-10
+
+.. option:: -freal-8-real-16, -fno-real-8-real-16
+
+.. option:: -freal-8-real-4, -fno-real-8-real-4
+
+.. option:: -frealloc-lhs, -fno-realloc-lhs
+
+.. option:: -frecord-marker=<arg>
+
+.. option:: -frecursive, -fno-recursive
+
+.. option:: -frepack-arrays, -fno-repack-arrays
+
+.. option:: -fsecond-underscore, -fno-second-underscore
+
+.. option:: -fsign-zero, -fno-sign-zero
+
+.. option:: -fstack-arrays, -fno-stack-arrays
+
+.. option:: -funderscoring, -fno-underscoring
+
+.. option:: -fwhole-file, -fno-whole-file
+
+.. option:: -imultilib <arg>
+
+.. option:: -nocpp
+
+.. option:: -static-libgfortran
+
+Linker flags
+============
+Flags that are passed on to the linker
+
+.. option:: -L<dir>, --library-directory <arg>, --library-directory=<arg>
+
+Add directory to library search path
+
+.. option:: -Mach
+
+.. option:: -T<script>
+
+Specify <script> as linker script
+
+.. option:: -Tbss<addr>
+
+Set starting address of BSS to <addr>
+
+.. option:: -Tdata<addr>
+
+Set starting address of DATA to <addr>
+
+.. option:: -Ttext<addr>
+
+Set starting address of TEXT to <addr>
+
+.. option:: -Wl,<arg>,<arg2>...
+
+Pass the comma separated arguments in <arg> to the linker
+
+.. option:: -X
+
+.. option:: -Xlinker <arg>, --for-linker <arg>, --for-linker=<arg>
+
+Pass <arg> to the linker
+
+.. program:: clang1
+.. option:: -Z
+.. program:: clang
+
+.. option:: -e<arg>, --entry
+
+.. option:: -filelist <arg>
+
+.. option:: --hip-device-lib-path=<arg>
+
+HIP device library path
+
+.. option:: --hip-device-lib=<arg>
+
+HIP device library
+
+.. option:: -l<arg>
+
+.. option:: -r
+
+.. option:: -rpath <arg>
+
+.. option:: -s
+
+.. option:: -t
+
+.. option:: -u<arg>, --force-link <arg>, --force-link=<arg>
+
+.. option:: -undef
+
+undef all system defines
+
+.. option:: -undefined<arg>, --no-undefined
+
+.. option:: -z <arg>
+
+Pass -z <arg> to the linker
+

Added: www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangFormat.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangFormat.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangFormat.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangFormat.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,210 @@
+===========
+ClangFormat
+===========
+
+`ClangFormat` describes a set of tools that are built on top of
+:doc:`LibFormat`. It can support your workflow in a variety of ways including a
+standalone tool and editor integrations.
+
+
+Standalone Tool
+===============
+
+:program:`clang-format` is located in `clang/tools/clang-format` and can be used
+to format C/C++/Java/JavaScript/Objective-C/Protobuf 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}"
+    -verbose                  - If set, shows the list of processed files
+
+  Generic Options:
+
+    -help                     - Display available options (-help-hidden for more)
+    -help-list                - Display list of available options (-help-list-hidden for more)
+    -version                  - Display the version of this program
+
+
+When the desired code formatting style is different from the available options,
+the style can be customized using the ``-style="{key: value, ...}"`` option or
+by putting your style configuration in the ``.clang-format`` or ``_clang-format``
+file in your project's directory and using ``clang-format -style=file``.
+
+An easy way to create the ``.clang-format`` file is:
+
+.. code-block:: console
+
+  clang-format -style=llvm -dump-config > .clang-format
+
+Available style options are described in :doc:`ClangFormatStyleOptions`.
+
+
+Vim Integration
+===============
+
+There is an integration for :program:`vim` which lets you run the
+:program:`clang-format` standalone tool on your current buffer, optionally
+selecting regions to reformat. The integration has the form of a `python`-file
+which can be found under `clang/tools/clang-format/clang-format.py`.
+
+This can be integrated by adding the following to your `.vimrc`:
+
+.. code-block:: vim
+
+  map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>
+  imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>
+
+The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the
+second line adds support for INSERT mode. Change "C-K" to another binding if
+you need :program:`clang-format` on a different key (C-K stands for Ctrl+k).
+
+With this integration you can press the bound key and clang-format will
+format the current line in NORMAL and INSERT mode or the selected region in
+VISUAL mode. The line or region is extended to the next bigger syntactic
+entity.
+
+It operates on the current, potentially unsaved buffer and does not create
+or save any files. To revert a formatting, just undo.
+
+An alternative option is to format changes when saving a file and thus to
+have a zero-effort integration into the coding workflow. To do this, add this to
+your `.vimrc`:
+
+.. code-block:: vim
+
+  function! Formatonsave()
+    let l:formatdiff = 1
+    pyf ~/llvm/tools/clang/tools/clang-format/clang-format.py
+  endfunction
+  autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave()
+
+
+Emacs Integration
+=================
+
+Similar to the integration for :program:`vim`, there is an integration for
+:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el`
+and used by adding this to your `.emacs`:
+
+.. code-block:: common-lisp
+
+  (load "<path-to-clang>/tools/clang-format/clang-format.el")
+  (global-set-key [C-M-tab] 'clang-format-region)
+
+This binds the function `clang-format-region` to C-M-tab, which then formats the
+current line or selected region.
+
+
+BBEdit Integration
+==================
+
+:program:`clang-format` cannot be used as a text filter with BBEdit, but works
+well via a script. The AppleScript to do this integration can be found at
+`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in
+`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to
+point to your local copy of :program:`clang-format`.
+
+With this integration you can select the script from the Script menu and
+:program:`clang-format` will format the selection. Note that you can rename the
+menu item by renaming the script, and can assign the menu item a keyboard
+shortcut in the BBEdit preferences, under Menus & Shortcuts.
+
+
+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/clang-format-diff.py` parses the
+output of a unified diff and reformats all contained lines with
+:program:`clang-format`.
+
+.. code-block:: console
+
+  usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE]
+
+  Reformat changed lines in diff. Without -i option just output the diff that
+  would be introduced.
+
+  optional arguments:
+    -h, --help      show this help message and exit
+    -i              apply edits to files instead of displaying a diff
+    -p NUM          strip the smallest prefix containing P slashes
+    -regex PATTERN  custom pattern selecting file paths to reformat
+    -style STYLE    formatting style to apply (LLVM, Google, Chromium, Mozilla,
+                    WebKit)
+
+So to reformat all the lines in the latest :program:`git` commit, just do:
+
+.. code-block:: console
+
+  git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1
+
+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/7.0.0/tools/clang/docs/_sources/ClangFormatStyleOptions.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangFormatStyleOptions.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangFormatStyleOptions.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangFormatStyleOptions.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,2115 @@
+==========================
+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;
+
+**AlignEscapedNewlines** (``EscapedNewlineAlignmentStyle``)
+  Options for aligning backslashes in escaped newlines.
+
+  Possible values:
+
+  * ``ENAS_DontAlign`` (in configuration: ``DontAlign``)
+    Don't align escaped newlines.
+
+    .. code-block:: c++
+
+      #define A \
+        int aaaa; \
+        int b; \
+        int dddddddddd;
+
+  * ``ENAS_Left`` (in configuration: ``Left``)
+    Align escaped newlines as far left as possible.
+
+    .. code-block:: c++
+
+      true:
+      #define A   \
+        int aaaa; \
+        int b;    \
+        int dddddddddd;
+
+      false:
+
+  * ``ENAS_Right`` (in configuration: ``Right``)
+    Align escaped newlines in the right-most column.
+
+    .. code-block:: c++
+
+      #define A                                                                      \
+        int aaaa;                                                                    \
+        int b;                                                                       \
+        int dddddddddd;
+
+
+
+**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.
+
+  .. code-block:: c++
+
+    true:                                   false:
+    int a;     // My comment a      vs.     int a; // My comment a
+    int b = 2; // comment  b                int b = 2; // comment about b
+
+**AllowAllParametersOfDeclarationOnNextLine** (``bool``)
+  If the function declaration doesn't fit on a line,
+  allow putting all parameters of a function declaration onto
+  the next line even if ``BinPackParameters`` is ``false``.
+
+  .. code-block:: c++
+
+    true:
+    void myFunction(
+        int a, int b, int c, int d, int e);
+
+    false:
+    void myFunction(int a,
+                    int b,
+                    int c,
+                    int d,
+                    int e);
+
+**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.
+
+  .. code-block:: c++
+
+    true:                                   false:
+    switch (a) {                    vs.     switch (a) {
+    case 1: x = 1; break;                   case 1:
+    case 2: return;                           x = 1;
+    }                                         break;
+                                            case 2:
+                                              return;
+                                            }
+
+**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_InlineOnly`` (in configuration: ``InlineOnly``)
+    Only merge functions defined inside a class. Same as "inline",
+    except it does not implies "empty": i.e. top level empty functions
+    are not merged either.
+
+    .. code-block:: c++
+
+      class Foo {
+        void f() { foo(); }
+      };
+      void f() {
+        foo();
+      }
+      void f() {
+      }
+
+  * ``SFS_Empty`` (in configuration: ``Empty``)
+    Only merge empty functions.
+
+    .. code-block:: c++
+
+      void f() {}
+      void f2() {
+        bar2();
+      }
+
+  * ``SFS_Inline`` (in configuration: ``Inline``)
+    Only merge functions defined inside a class. Implies "empty".
+
+    .. code-block:: c++
+
+      class Foo {
+        void f() { foo(); }
+      };
+      void f() {
+        foo();
+      }
+      void f() {}
+
+  * ``SFS_All`` (in configuration: ``All``)
+    Merge all functions fitting on a single line.
+
+    .. code-block:: c++
+
+      class Foo {
+        void f() { foo(); }
+      };
+      void f() { bar(); }
+
+
+
+**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.
+
+    .. code-block:: c++
+
+      class A {
+        int f() { return 0; };
+      };
+      int f();
+      int f() { return 1; }
+
+  * ``RTBS_All`` (in configuration: ``All``)
+    Always break after the return type.
+
+    .. code-block:: c++
+
+      class A {
+        int
+        f() {
+          return 0;
+        };
+      };
+      int
+      f();
+      int
+      f() {
+        return 1;
+      }
+
+  * ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
+    Always break after the return types of top-level functions.
+
+    .. code-block:: c++
+
+      class A {
+        int f() { return 0; };
+      };
+      int
+      f();
+      int
+      f() {
+        return 1;
+      }
+
+  * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
+    Always break after the return type of function definitions.
+
+    .. code-block:: c++
+
+      class A {
+        int
+        f() {
+          return 0;
+        };
+      };
+      int f();
+      int
+      f() {
+        return 1;
+      }
+
+  * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
+    Always break after the return type of top-level definitions.
+
+    .. code-block:: c++
+
+      class A {
+        int f() { return 0; };
+      };
+      int f();
+      int
+      f() {
+        return 1;
+      }
+
+
+
+**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.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     aaaa =                         vs.     aaaa = "bbbb"
+         "bbbb"                                    "cccc";
+         "cccc";
+
+**AlwaysBreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``)
+  The template declaration breaking style to use.
+
+  Possible values:
+
+  * ``BTDS_No`` (in configuration: ``No``)
+    Do not force break before declaration.
+    ``PenaltyBreakTemplateDeclaration`` is taken into account.
+
+    .. code-block:: c++
+
+       template <typename T> T foo() {
+       }
+       template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
+                                   int bbbbbbbbbbbbbbbbbbbbb) {
+       }
+
+  * ``BTDS_MultiLine`` (in configuration: ``MultiLine``)
+    Force break after template declaration only when the following
+    declaration spans multiple lines.
+
+    .. code-block:: c++
+
+       template <typename T> T foo() {
+       }
+       template <typename T>
+       T foo(int aaaaaaaaaaaaaaaaaaaaa,
+             int bbbbbbbbbbbbbbbbbbbbb) {
+       }
+
+  * ``BTDS_Yes`` (in configuration: ``Yes``)
+    Always break after template declaration.
+
+    .. code-block:: c++
+
+       template <typename T>
+       T foo() {
+       }
+       template <typename T>
+       T foo(int aaaaaaaaaaaaaaaaaaaaa,
+             int bbbbbbbbbbbbbbbbbbbbb) {
+       }
+
+
+
+**BinPackArguments** (``bool``)
+  If ``false``, a function call's arguments will either be all on the
+  same line or will have one line each.
+
+  .. code-block:: c++
+
+    true:
+    void f() {
+      f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
+        aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+    }
+
+    false:
+    void f() {
+      f(aaaaaaaaaaaaaaaaaaaa,
+        aaaaaaaaaaaaaaaaaaaa,
+        aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+    }
+
+**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.
+
+  .. code-block:: c++
+
+    true:
+    void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
+           int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
+
+    false:
+    void f(int aaaaaaaaaaaaaaaaaaaa,
+           int aaaaaaaaaaaaaaaaaaaa,
+           int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
+
+**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.
+
+  .. code-block:: yaml
+
+    # Example of usage:
+    BreakBeforeBraces: Custom
+    BraceWrapping:
+      AfterEnum: true
+      AfterStruct: false
+      SplitEmptyFunction: false
+
+  Nested configuration flags:
+
+
+  * ``bool AfterClass`` Wrap class definitions.
+
+    .. code-block:: c++
+
+      true:
+      class foo {};
+
+      false:
+      class foo
+      {};
+
+  * ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..).
+
+    .. code-block:: c++
+
+      true:
+      if (foo())
+      {
+      } else
+      {}
+      for (int i = 0; i < 10; ++i)
+      {}
+
+      false:
+      if (foo()) {
+      } else {
+      }
+      for (int i = 0; i < 10; ++i) {
+      }
+
+  * ``bool AfterEnum`` Wrap enum definitions.
+
+    .. code-block:: c++
+
+      true:
+      enum X : int
+      {
+        B
+      };
+
+      false:
+      enum X : int { B };
+
+  * ``bool AfterFunction`` Wrap function definitions.
+
+    .. code-block:: c++
+
+      true:
+      void foo()
+      {
+        bar();
+        bar2();
+      }
+
+      false:
+      void foo() {
+        bar();
+        bar2();
+      }
+
+  * ``bool AfterNamespace`` Wrap namespace definitions.
+
+    .. code-block:: c++
+
+      true:
+      namespace
+      {
+      int foo();
+      int bar();
+      }
+
+      false:
+      namespace {
+      int foo();
+      int bar();
+      }
+
+  * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...).
+    @autoreleasepool and @synchronized blocks are wrapped
+    according to `AfterControlStatement` flag.
+
+  * ``bool AfterStruct`` Wrap struct definitions.
+
+    .. code-block:: c++
+
+      true:
+      struct foo
+      {
+        int x;
+      };
+
+      false:
+      struct foo {
+        int x;
+      };
+
+  * ``bool AfterUnion`` Wrap union definitions.
+
+    .. code-block:: c++
+
+      true:
+      union foo
+      {
+        int x;
+      }
+
+      false:
+      union foo {
+        int x;
+      }
+
+  * ``bool AfterExternBlock`` Wrap extern blocks.
+
+    .. code-block:: c++
+
+      true:
+      extern "C"
+      {
+        int foo();
+      }
+
+      false:
+      extern "C" {
+      int foo();
+      }
+
+  * ``bool BeforeCatch`` Wrap before ``catch``.
+
+    .. code-block:: c++
+
+      true:
+      try {
+        foo();
+      }
+      catch () {
+      }
+
+      false:
+      try {
+        foo();
+      } catch () {
+      }
+
+  * ``bool BeforeElse`` Wrap before ``else``.
+
+    .. code-block:: c++
+
+      true:
+      if (foo()) {
+      }
+      else {
+      }
+
+      false:
+      if (foo()) {
+      } else {
+      }
+
+  * ``bool IndentBraces`` Indent the wrapped braces themselves.
+
+  * ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line.
+    This option is used only if the opening brace of the function has
+    already been wrapped, i.e. the `AfterFunction` brace wrapping mode is
+    set, and the function could/should not be put on a single line (as per
+    `AllowShortFunctionsOnASingleLine` and constructor formatting options).
+
+    .. code-block:: c++
+
+      int f()   vs.   inf f()
+      {}              {
+                      }
+
+  * ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body
+    can be put on a single line. This option is used only if the opening
+    brace of the record has already been wrapped, i.e. the `AfterClass`
+    (for classes) brace wrapping mode is set.
+
+    .. code-block:: c++
+
+      class Foo   vs.  class Foo
+      {}               {
+                       }
+
+  * ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line.
+    This option is used only if the opening brace of the namespace has
+    already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is
+    set.
+
+    .. code-block:: c++
+
+      namespace Foo   vs.  namespace Foo
+      {}                   {
+                           }
+
+
+**BreakAfterJavaFieldAnnotations** (``bool``)
+  Break after each annotation on a field in Java files.
+
+  .. code-block:: java
+
+     true:                                  false:
+     @Partial                       vs.     @Partial @Mock DataLoad loader;
+     @Mock
+     DataLoad loader;
+
+**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``)
+  The way to wrap binary operators.
+
+  Possible values:
+
+  * ``BOS_None`` (in configuration: ``None``)
+    Break after operators.
+
+    .. code-block:: c++
+
+       LooooooooooongType loooooooooooooooooooooongVariable =
+           someLooooooooooooooooongFunction();
+
+       bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
+                            aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
+                        aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
+                    aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
+                        ccccccccccccccccccccccccccccccccccccccccc;
+
+  * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
+    Break before operators that aren't assignments.
+
+    .. code-block:: c++
+
+       LooooooooooongType loooooooooooooooooooooongVariable =
+           someLooooooooooooooooongFunction();
+
+       bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                            + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                        == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                    && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                           > ccccccccccccccccccccccccccccccccccccccccc;
+
+  * ``BOS_All`` (in configuration: ``All``)
+    Break before operators.
+
+    .. code-block:: c++
+
+       LooooooooooongType loooooooooooooooooooooongVariable
+           = someLooooooooooooooooongFunction();
+
+       bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                            + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                        == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                    && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+                           > ccccccccccccccccccccccccccccccccccccccccc;
+
+
+
+**BreakBeforeBraces** (``BraceBreakingStyle``)
+  The brace breaking style to use.
+
+  Possible values:
+
+  * ``BS_Attach`` (in configuration: ``Attach``)
+    Always attach braces to surrounding context.
+
+    .. code-block:: c++
+
+      try {
+        foo();
+      } catch () {
+      }
+      void foo() { bar(); }
+      class foo {};
+      if (foo()) {
+      } else {
+      }
+      enum X : int { A, B };
+
+  * ``BS_Linux`` (in configuration: ``Linux``)
+    Like ``Attach``, but break before braces on function, namespace and
+    class definitions.
+
+    .. code-block:: c++
+
+      try {
+        foo();
+      } catch () {
+      }
+      void foo() { bar(); }
+      class foo
+      {
+      };
+      if (foo()) {
+      } else {
+      }
+      enum X : int { A, B };
+
+  * ``BS_Mozilla`` (in configuration: ``Mozilla``)
+    Like ``Attach``, but break before braces on enum, function, and record
+    definitions.
+
+    .. code-block:: c++
+
+      try {
+        foo();
+      } catch () {
+      }
+      void foo() { bar(); }
+      class foo
+      {
+      };
+      if (foo()) {
+      } else {
+      }
+      enum X : int { A, B };
+
+  * ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
+    Like ``Attach``, but break before function definitions, ``catch``, and
+    ``else``.
+
+    .. code-block:: c++
+
+      try {
+        foo();
+      } catch () {
+      }
+      void foo() { bar(); }
+      class foo
+      {
+      };
+      if (foo()) {
+      } else {
+      }
+      enum X : int
+      {
+        A,
+        B
+      };
+
+  * ``BS_Allman`` (in configuration: ``Allman``)
+    Always break before braces.
+
+    .. code-block:: c++
+
+      try {
+        foo();
+      }
+      catch () {
+      }
+      void foo() { bar(); }
+      class foo {
+      };
+      if (foo()) {
+      }
+      else {
+      }
+      enum X : int { A, B };
+
+  * ``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.
+
+    .. code-block:: c++
+
+      try
+        {
+          foo();
+        }
+      catch ()
+        {
+        }
+      void foo() { bar(); }
+      class foo
+      {
+      };
+      if (foo())
+        {
+        }
+      else
+        {
+        }
+      enum X : int
+      {
+        A,
+        B
+      };
+
+  * ``BS_WebKit`` (in configuration: ``WebKit``)
+    Like ``Attach``, but break before functions.
+
+    .. code-block:: c++
+
+      try {
+        foo();
+      } catch () {
+      }
+      void foo() { bar(); }
+      class foo {
+      };
+      if (foo()) {
+      } else {
+      }
+      enum X : int { A, B };
+
+  * ``BS_Custom`` (in configuration: ``Custom``)
+    Configure each individual brace in `BraceWrapping`.
+
+
+
+**BreakBeforeTernaryOperators** (``bool``)
+  If ``true``, ternary operators will be placed after line breaks.
+
+  .. code-block:: c++
+
+     true:
+     veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
+         ? firstValue
+         : SecondValueVeryVeryVeryVeryLong;
+
+     false:
+     veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
+         firstValue :
+         SecondValueVeryVeryVeryVeryLong;
+
+**BreakConstructorInitializers** (``BreakConstructorInitializersStyle``)
+  The constructor initializers style to use.
+
+  Possible values:
+
+  * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``)
+    Break constructor initializers before the colon and after the commas.
+
+    .. code-block:: c++
+
+       Constructor()
+           : initializer1(),
+             initializer2()
+
+  * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``)
+    Break constructor initializers before the colon and commas, and align
+    the commas with the colon.
+
+    .. code-block:: c++
+
+       Constructor()
+           : initializer1()
+           , initializer2()
+
+  * ``BCIS_AfterColon`` (in configuration: ``AfterColon``)
+    Break constructor initializers after the colon and commas.
+
+    .. code-block:: c++
+
+       Constructor() :
+           initializer1(),
+           initializer2()
+
+
+
+**BreakInheritanceList** (``BreakInheritanceListStyle``)
+  The inheritance list style to use.
+
+  Possible values:
+
+  * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``)
+    Break inheritance list before the colon and after the commas.
+
+    .. code-block:: c++
+
+       class Foo
+           : Base1,
+             Base2
+       {};
+
+  * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``)
+    Break inheritance list before the colon and commas, and align
+    the commas with the colon.
+
+    .. code-block:: c++
+
+       class Foo
+           : Base1
+           , Base2
+       {};
+
+  * ``BILS_AfterColon`` (in configuration: ``AfterColon``)
+    Break inheritance list after the colon and commas.
+
+    .. code-block:: c++
+
+       class Foo :
+           Base1,
+           Base2
+       {};
+
+
+
+**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.
+
+  .. code-block:: c++
+
+     // CommentPragmas: '^ FOOBAR pragma:'
+     // Will leave the following line unaffected
+     #include <vector> // FOOBAR pragma: keep
+
+**CompactNamespaces** (``bool``)
+  If ``true``, consecutive namespace declarations will be on the same
+  line. If ``false``, each namespace is declared on a new line.
+
+  .. code-block:: c++
+
+    true:
+    namespace Foo { namespace Bar {
+    }}
+
+    false:
+    namespace Foo {
+    namespace Bar {
+    }
+    }
+
+  If it does not fit on a single line, the overflowing namespaces get
+  wrapped:
+
+  .. code-block:: c++
+
+    namespace Foo { namespace Bar {
+    namespace Extra {
+    }}}
+
+**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
+  If the constructor initializers don't fit on a line, put each
+  initializer on its own line.
+
+  .. code-block:: c++
+
+    true:
+    FitsOnOneLine::Constructor()
+        : aaaaaaaaaaaaa(aaaaaaaaaaaaaa), aaaaaaaaaaaaa(aaaaaaaaaaaaaa) {}
+
+    DoesntFit::Constructor()
+        : aaaaaaaaaaaaa(aaaaaaaaaaaaaa),
+          aaaaaaaaaaaaa(aaaaaaaaaaaaaa),
+          aaaaaaaaaaaaa(aaaaaaaaaaaaaa) {}
+
+    false:
+    FitsOnOneLine::Constructor()
+        : aaaaaaaaaaaaa(aaaaaaaaaaaaaa), aaaaaaaaaaaaa(aaaaaaaaaaaaaa) {}
+
+    DoesntFit::Constructor()
+        : aaaaaaaaaaaaa(aaaaaaaaaaaaaa), aaaaaaaaaaaaa(aaaaaaaaaaaaaa),
+          aaaaaaaaaaaaa(aaaaaaaaaaaaaa) {}
+
+**ConstructorInitializerIndentWidth** (``unsigned``)
+  The number of characters to use for indentation of constructor
+  initializer lists as well as inheritance lists.
+
+**ContinuationIndentWidth** (``unsigned``)
+  Indent width for line continuations.
+
+  .. code-block:: c++
+
+     ContinuationIndentWidth: 2
+
+     int i =         //  VeryVeryVeryVeryVeryLongComment
+       longFunction( // Again a long comment
+         arg);
+
+**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.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     vector<int> x{1, 2, 3, 4};     vs.     vector<int> x{ 1, 2, 3, 4 };
+     vector<T> x{{}, {}, {}, {}};           vector<T> x{ {}, {}, {}, {} };
+     f(MyMap[{composite, key}]);            f(MyMap[{ composite, key }]);
+     new int[3]{1, 2, 3};                   new int[3]{ 1, 2, 3 };
+
+**DerivePointerAlignment** (``bool``)
+  If ``true``, analyze the formatted file for the most common
+  alignment of ``&`` and ``*``.
+  Pointer and reference alignment styles are going to be updated according
+  to the preferences found in the file.
+  ``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.
+
+**FixNamespaceComments** (``bool``)
+  If ``true``, clang-format adds missing namespace end comments and
+  fixes invalid existing ones.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     namespace a {                  vs.     namespace a {
+     foo();                                 foo();
+     } // namespace a;                      }
+
+**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.
+
+**IncludeBlocks** (``IncludeBlocksStyle``)
+  Dependent on the value, multiple ``#include`` blocks can be sorted
+  as one and divided based on category.
+
+  Possible values:
+
+  * ``IBS_Preserve`` (in configuration: ``Preserve``)
+    Sort each ``#include`` block separately.
+
+    .. code-block:: c++
+
+       #include "b.h"               into      #include "b.h"
+
+       #include <lib/main.h>                  #include "a.h"
+       #include "a.h"                         #include <lib/main.h>
+
+  * ``IBS_Merge`` (in configuration: ``Merge``)
+    Merge multiple ``#include`` blocks together and sort as one.
+
+    .. code-block:: c++
+
+       #include "b.h"               into      #include "a.h"
+                                              #include "b.h"
+       #include <lib/main.h>                  #include <lib/main.h>
+       #include "a.h"
+
+  * ``IBS_Regroup`` (in configuration: ``Regroup``)
+    Merge multiple ``#include`` blocks together and sort as one.
+    Then split into groups based on category priority. See
+    ``IncludeCategories``.
+
+    .. code-block:: c++
+
+       #include "b.h"               into      #include "a.h"
+                                              #include "b.h"
+       #include <lib/main.h>
+       #include "a.h"                         #include <lib/main.h>
+
+
+
+**IncludeCategories** (``std::vector<IncludeCategory>``)
+  Regular expressions denoting the different ``#include`` categories
+  used for ordering ``#includes``.
+
+  `POSIX extended
+  <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
+  regular expressions are supported.
+
+  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|gmock|isl|json)/)'
+        Priority:        3
+      - Regex:           '<[[:alnum:].]+>'
+        Priority:        4
+      - 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.
+
+  .. code-block:: c++
+
+     false:                                 true:
+     switch (fool) {                vs.     switch (fool) {
+     case 1:                                  case 1:
+       bar();                                   bar();
+       break;                                   break;
+     default:                                 default:
+       plop();                                  plop();
+     }                                      }
+
+**IndentPPDirectives** (``PPDirectiveIndentStyle``)
+  The preprocessor directive indenting style to use.
+
+  Possible values:
+
+  * ``PPDIS_None`` (in configuration: ``None``)
+    Does not indent any directives.
+
+    .. code-block:: c++
+
+       #if FOO
+       #if BAR
+       #include <foo>
+       #endif
+       #endif
+
+  * ``PPDIS_AfterHash`` (in configuration: ``AfterHash``)
+    Indents directives after the hash.
+
+    .. code-block:: c++
+
+       #if FOO
+       #  if BAR
+       #    include <foo>
+       #  endif
+       #endif
+
+
+
+**IndentWidth** (``unsigned``)
+  The number of columns to use for indentation.
+
+  .. code-block:: c++
+
+     IndentWidth: 3
+
+     void f() {
+        someFunction();
+        if (true, false) {
+           f();
+        }
+     }
+
+**IndentWrappedFunctionNames** (``bool``)
+  Indent if a function definition or declaration is wrapped after the
+  type.
+
+  .. code-block:: c++
+
+     true:
+     LoooooooooooooooooooooooooooooooooooooooongReturnType
+         LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+
+     false:
+     LoooooooooooooooooooooooooooooooooooooooongReturnType
+     LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+
+**JavaScriptQuotes** (``JavaScriptQuoteStyle``)
+  The JavaScriptQuoteStyle to use for JavaScript strings.
+
+  Possible values:
+
+  * ``JSQS_Leave`` (in configuration: ``Leave``)
+    Leave string quotes as they are.
+
+    .. code-block:: js
+
+       string1 = "foo";
+       string2 = 'bar';
+
+  * ``JSQS_Single`` (in configuration: ``Single``)
+    Always use single quotes.
+
+    .. code-block:: js
+
+       string1 = 'foo';
+       string2 = 'bar';
+
+  * ``JSQS_Double`` (in configuration: ``Double``)
+    Always use double quotes.
+
+    .. code-block:: js
+
+       string1 = "foo";
+       string2 = "bar";
+
+
+
+**JavaScriptWrapImports** (``bool``)
+  Whether to wrap JavaScript import/export statements.
+
+  .. code-block:: js
+
+     true:
+     import {
+         VeryLongImportsAreAnnoying,
+         VeryLongImportsAreAnnoying,
+         VeryLongImportsAreAnnoying,
+     } from 'some/module.js'
+
+     false:
+     import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
+
+**KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
+  If true, the empty line at the start of blocks is kept.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     if (foo) {                     vs.     if (foo) {
+                                              bar();
+       bar();                               }
+     }
+
+**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++.
+
+  * ``LK_Java`` (in configuration: ``Java``)
+    Should be used for Java.
+
+  * ``LK_JavaScript`` (in configuration: ``JavaScript``)
+    Should be used for JavaScript.
+
+  * ``LK_ObjC`` (in configuration: ``ObjC``)
+    Should be used for Objective-C, Objective-C++.
+
+  * ``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.
+
+  * ``LK_TextProto`` (in configuration: ``TextProto``)
+    Should be used for Protocol Buffer messages in text format
+    (https://developers.google.com/protocol-buffers/).
+
+
+
+**MacroBlockBegin** (``std::string``)
+  A regular expression matching macros that start a block.
+
+  .. code-block:: c++
+
+     # With:
+     MacroBlockBegin: "^NS_MAP_BEGIN|\
+     NS_TABLE_HEAD$"
+     MacroBlockEnd: "^\
+     NS_MAP_END|\
+     NS_TABLE_.*_END$"
+
+     NS_MAP_BEGIN
+       foo();
+     NS_MAP_END
+
+     NS_TABLE_HEAD
+       bar();
+     NS_TABLE_FOO_END
+
+     # Without:
+     NS_MAP_BEGIN
+     foo();
+     NS_MAP_END
+
+     NS_TABLE_HEAD
+     bar();
+     NS_TABLE_FOO_END
+
+**MacroBlockEnd** (``std::string``)
+  A regular expression matching macros that end a block.
+
+**MaxEmptyLinesToKeep** (``unsigned``)
+  The maximum number of consecutive empty lines to keep.
+
+  .. code-block:: c++
+
+     MaxEmptyLinesToKeep: 1         vs.     MaxEmptyLinesToKeep: 0
+     int f() {                              int f() {
+       int = 1;                                 int i = 1;
+                                                i = foo();
+       i = foo();                               return i;
+                                            }
+       return i;
+     }
+
+**NamespaceIndentation** (``NamespaceIndentationKind``)
+  The indentation used for namespaces.
+
+  Possible values:
+
+  * ``NI_None`` (in configuration: ``None``)
+    Don't indent in namespaces.
+
+    .. code-block:: c++
+
+       namespace out {
+       int i;
+       namespace in {
+       int i;
+       }
+       }
+
+  * ``NI_Inner`` (in configuration: ``Inner``)
+    Indent only in inner namespaces (nested in other namespaces).
+
+    .. code-block:: c++
+
+       namespace out {
+       int i;
+       namespace in {
+         int i;
+       }
+       }
+
+  * ``NI_All`` (in configuration: ``All``)
+    Indent in all namespaces.
+
+    .. code-block:: c++
+
+       namespace out {
+         int i;
+         namespace in {
+           int i;
+         }
+       }
+
+
+
+**ObjCBinPackProtocolList** (``BinPackStyle``)
+  Controls bin-packing Objective-C protocol conformance list
+  items into as few lines as possible when they go over ``ColumnLimit``.
+
+  If ``Auto`` (the default), delegates to the value in
+  ``BinPackParameters``. If that is ``true``, bin-packs Objective-C
+  protocol conformance list items into as few lines as possible
+  whenever they go over ``ColumnLimit``.
+
+  If ``Always``, always bin-packs Objective-C protocol conformance
+  list items into as few lines as possible whenever they go over
+  ``ColumnLimit``.
+
+  If ``Never``, lays out Objective-C protocol conformance list items
+  onto individual lines whenever they go over ``ColumnLimit``.
+
+
+  .. code-block:: objc
+
+     Always (or Auto, if BinPackParameters=true):
+     @interface ccccccccccccc () <
+         ccccccccccccc, ccccccccccccc,
+         ccccccccccccc, ccccccccccccc> {
+     }
+
+     Never (or Auto, if BinPackParameters=false):
+     @interface ddddddddddddd () <
+         ddddddddddddd,
+         ddddddddddddd,
+         ddddddddddddd,
+         ddddddddddddd> {
+     }
+
+  Possible values:
+
+  * ``BPS_Auto`` (in configuration: ``Auto``)
+    Automatically determine parameter bin-packing behavior.
+
+  * ``BPS_Always`` (in configuration: ``Always``)
+    Always bin-pack parameters.
+
+  * ``BPS_Never`` (in configuration: ``Never``)
+    Never bin-pack parameters.
+
+
+
+**ObjCBlockIndentWidth** (``unsigned``)
+  The number of characters to use for indentation of ObjC blocks.
+
+  .. code-block:: objc
+
+     ObjCBlockIndentWidth: 4
+
+     [operation setCompletionBlock:^{
+         [self onOperationDone];
+     }];
+
+**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>``.
+
+**PenaltyBreakAssignment** (``unsigned``)
+  The penalty for breaking around an assignment operator.
+
+**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.
+
+**PenaltyBreakTemplateDeclaration** (``unsigned``)
+  The penalty for breaking after template declaration.
+
+**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.
+
+    .. code-block:: c++
+
+      int* a;
+
+  * ``PAS_Right`` (in configuration: ``Right``)
+    Align pointer to the right.
+
+    .. code-block:: c++
+
+      int *a;
+
+  * ``PAS_Middle`` (in configuration: ``Middle``)
+    Align pointer in the middle.
+
+    .. code-block:: c++
+
+      int * a;
+
+
+
+**RawStringFormats** (``std::vector<RawStringFormat>``)
+  Defines hints for detecting supported languages code blocks in raw
+  strings.
+
+  A raw string with a matching delimiter or a matching enclosing function
+  name will be reformatted assuming the specified language based on the
+  style for that language defined in the .clang-format file. If no style has
+  been defined in the .clang-format file for the specific language, a
+  predefined style given by 'BasedOnStyle' is used. If 'BasedOnStyle' is not
+  found, the formatting is based on llvm style. A matching delimiter takes
+  precedence over a matching enclosing function name for determining the
+  language of the raw string contents.
+
+  If a canonical delimiter is specified, occurrences of other delimiters for
+  the same language will be updated to the canonical if possible.
+
+  There should be at most one specification per language and each delimiter
+  and enclosing function should not occur in multiple specifications.
+
+  To configure this in the .clang-format file, use:
+
+  .. code-block:: yaml
+
+    RawStringFormats:
+      - Language: TextProto
+          Delimiters:
+            - 'pb'
+            - 'proto'
+          EnclosingFunctions:
+            - 'PARSE_TEXT_PROTO'
+          BasedOnStyle: google
+      - Language: Cpp
+          Delimiters:
+            - 'cc'
+            - 'cpp'
+          BasedOnStyle: llvm
+          CanonicalDelimiter: 'cc'
+
+**ReflowComments** (``bool``)
+  If ``true``, clang-format will attempt to re-flow comments.
+
+  .. code-block:: c++
+
+     false:
+     // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+     /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+
+     true:
+     // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+     // information
+     /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+      * information */
+
+**SortIncludes** (``bool``)
+  If ``true``, clang-format will sort ``#includes``.
+
+  .. code-block:: c++
+
+     false:                                 true:
+     #include "b.h"                 vs.     #include "a.h"
+     #include "a.h"                         #include "b.h"
+
+**SortUsingDeclarations** (``bool``)
+  If ``true``, clang-format will sort using declarations.
+
+  The order of using declarations is defined as follows:
+  Split the strings by "::" and discard any initial empty strings. The last
+  element of each list is a non-namespace name; all others are namespace
+  names. Sort the lists of names lexicographically, where the sort order of
+  individual names is that all non-namespace names come before all namespace
+  names, and within those groups, names are in case-insensitive
+  lexicographic order.
+
+  .. code-block:: c++
+
+     false:                                 true:
+     using std::cout;               vs.     using std::cin;
+     using std::cin;                        using std::cout;
+
+**SpaceAfterCStyleCast** (``bool``)
+  If ``true``, a space is inserted after C style casts.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     (int) i;                       vs.     (int)i;
+
+**SpaceAfterTemplateKeyword** (``bool``)
+  If ``true``, a space will be inserted after the 'template' keyword.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     template <int> void foo();     vs.     template<int> void foo();
+
+**SpaceBeforeAssignmentOperators** (``bool``)
+  If ``false``, spaces will be removed before assignment operators.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     int a = 5;                     vs.     int a=5;
+     a += 42                                a+=42;
+
+**SpaceBeforeCpp11BracedList** (``bool``)
+  If ``true``, a space will be inserted before a C++11 braced list
+  used to initialize an object (after the preceding identifier or type).
+
+  .. code-block:: c++
+
+     true:                                  false:
+     Foo foo { bar };               vs.     Foo foo{ bar };
+     Foo {};                                Foo{};
+     vector<int> { 1, 2, 3 };               vector<int>{ 1, 2, 3 };
+     new int[3] { 1, 2, 3 };                new int[3]{ 1, 2, 3 };
+
+**SpaceBeforeCtorInitializerColon** (``bool``)
+  If ``false``, spaces will be removed before constructor initializer
+  colon.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     Foo::Foo() : a(a) {}                   Foo::Foo(): a(a) {}
+
+**SpaceBeforeInheritanceColon** (``bool``)
+  If ``false``, spaces will be removed before inheritance colon.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     class Foo : Bar {}             vs.     class Foo: Bar {}
+
+**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.
+
+    .. code-block:: c++
+
+       void f() {
+         if(true) {
+           f();
+         }
+       }
+
+  * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
+    Put a space before opening parentheses only after control statement
+    keywords (``for/if/while...``).
+
+    .. code-block:: c++
+
+       void f() {
+         if (true) {
+           f();
+         }
+       }
+
+  * ``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.)
+
+    .. code-block:: c++
+
+       void f () {
+         if (true) {
+           f ();
+         }
+       }
+
+
+
+**SpaceBeforeRangeBasedForLoopColon** (``bool``)
+  If ``false``, spaces will be removed before range-based for loop
+  colon.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     for (auto v : values) {}       vs.     for(auto v: values) {}
+
+**SpaceInEmptyParentheses** (``bool``)
+  If ``true``, spaces may be inserted into ``()``.
+
+  .. code-block:: c++
+
+     true:                                false:
+     void f( ) {                    vs.   void f() {
+       int x[] = {foo( ), bar( )};          int x[] = {foo(), bar()};
+       if (true) {                          if (true) {
+         f( );                                f();
+       }                                    }
+     }                                    }
+
+**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.
+
+  .. code-block:: c++
+
+     SpacesBeforeTrailingComments: 3
+     void f() {
+       if (true) {   // foo1
+         f();        // bar
+       }             // foo
+     }
+
+**SpacesInAngles** (``bool``)
+  If ``true``, spaces will be inserted after ``<`` and before ``>``
+  in template argument lists.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     static_cast< int >(arg);       vs.     static_cast<int>(arg);
+     std::function< void(int) > fct;        std::function<void(int)> fct;
+
+**SpacesInCStyleCastParentheses** (``bool``)
+  If ``true``, spaces may be inserted into C style casts.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     x = ( int32 )y                 vs.     x = (int32)y
+
+**SpacesInContainerLiterals** (``bool``)
+  If ``true``, spaces are inserted inside container literals (e.g.
+  ObjC and Javascript array and dict literals).
+
+  .. code-block:: js
+
+     true:                                  false:
+     var arr = [ 1, 2, 3 ];         vs.     var arr = [1, 2, 3];
+     f({a : 1, b : 2, c : 3});              f({a: 1, b: 2, c: 3});
+
+**SpacesInParentheses** (``bool``)
+  If ``true``, spaces will be inserted after ``(`` and before ``)``.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     t f( Deleted & ) & = delete;   vs.     t f(Deleted &) & = delete;
+
+**SpacesInSquareBrackets** (``bool``)
+  If ``true``, spaces will be inserted after ``[`` and before ``]``.
+  Lambdas or unspecified size array declarations will not be affected.
+
+  .. code-block:: c++
+
+     true:                                  false:
+     int a[ 5 ];                    vs.     int a[5];
+     std::unique_ptr<int[]> foo() {} // Won't be affected
+
+**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, C++14 and C++1z (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_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``)
+    Use tabs only for line continuation and 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/7.0.0/tools/clang/docs/_sources/ClangPlugins.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangPlugins.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangPlugins.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangPlugins.rst.txt Wed Sep 19 02:40:08 2018
@@ -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/7.0.0/tools/clang/docs/_sources/ClangTools.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangTools.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangTools.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/ClangTools.rst.txt Wed Sep 19 02:40:08 2018
@@ -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/7.0.0/tools/clang/docs/_sources/CommandGuide/clang.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/CommandGuide/clang.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/CommandGuide/clang.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/CommandGuide/clang.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,636 @@
+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=<standard>
+
+ Specify the language standard to compile for.
+
+ Supported values for the C language are:
+
+  | ``c89``
+  | ``c90``
+  | ``iso9899:1990``
+
+   ISO C 1990
+
+  | ``iso9899:199409``
+
+   ISO C 1990 with amendment 1
+
+  | ``gnu89``
+  | ``gnu90``
+
+   ISO C 1990 with GNU extensions
+
+  | ``c99``
+  | ``iso9899:1999``
+
+   ISO C 1999
+
+  | ``gnu99``
+
+   ISO C 1999 with GNU extensions
+
+  | ``c11``
+  | ``iso9899:2011``
+
+   ISO C 2011
+
+  | ``gnu11``
+
+   ISO C 2011 with GNU extensions
+
+  | ``c17``
+  | ``iso9899:2017``
+
+   ISO C 2017
+
+  | ``gnu17``
+
+   ISO C 2017 with GNU extensions
+
+ The default C language standard is ``gnu11``, except on PS4, where it is
+ ``gnu99``.
+
+ Supported values for the C++ language are:
+
+  | ``c++98``
+  | ``c++03``
+
+   ISO C++ 1998 with amendments
+
+  | ``gnu++98``
+  | ``gnu++03``
+
+   ISO C++ 1998 with amendments and GNU extensions
+
+  | ``c++11``
+
+   ISO C++ 2011 with amendments
+
+  | ``gnu++11``
+
+    ISO C++ 2011 with amendments and GNU extensions
+
+  | ``c++14``
+
+   ISO C++ 2014 with amendments
+
+  | ``gnu++14``
+
+   ISO C++ 2014 with amendments and GNU extensions
+
+  | ``c++17``
+
+   ISO C++ 2017 with amendments
+
+  | ``gnu++17``
+
+   ISO C++ 2017 with amendments and GNU extensions
+
+  | ``c++2a``
+
+   Working draft for ISO C++ 2020
+
+  | ``gnu++2a``
+
+   Working draft for ISO C++ 2020 with GNU extensions
+
+ The default C++ language standard is ``gnu++14``.
+
+ Supported values for the OpenCL language are:
+
+  | ``cl1.0``
+
+   OpenCL 1.0
+
+  | ``cl1.1``
+
+   OpenCL 1.1
+
+  | ``cl1.2``
+
+   OpenCL 1.2
+
+  | ``cl2.0``
+
+   OpenCL 2.0
+
+ The default OpenCL language standard is ``cl1.0``.
+
+ Supported values for the CUDA language are:
+
+  | ``cuda``
+
+   NVIDIA CUDA(tm)
+
+.. option:: -stdlib=<library>
+
+ Specify the C++ standard library to use; supported options are libstdc++ and
+ libc++. If not specified, platform default will be used.
+
+.. option:: -rtlib=<library>
+
+ Specify the compiler runtime library to use; supported options are libgcc and
+ compiler-rt. If not specified, platform default will be used.
+
+.. 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-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, -Og, -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:`-Og` Like :option:`-O1`. In future versions, this option might 
+    disable different optimizations in order to improve debuggability.
+
+    :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, -flto=full, -flto=thin, -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).
+
+  The default for :option:`-flto` is "full", in which the
+  LLVM bitcode is suitable for monolithic Link Time Optimization (LTO), where
+  the linker merges all such modules into a single combined module for
+  optimization. With "thin", :doc:`ThinLTO <../ThinLTO>`
+  compilation is invoked instead.
+
+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 the currently used compiler runtime library
+  ("libgcc.a" or "libclang_rt.builtins.*.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:: -save-stats, -save-stats=cwd, -save-stats=obj
+
+  Save internal code generation (LLVM) statistics to a file in the current
+  directory (:option:`-save-stats`/"-save-stats=cwd") or the directory
+  of the output file ("-save-state=obj").
+
+.. 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/7.0.0/tools/clang/docs/_sources/CommandGuide/diagtool.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/CommandGuide/diagtool.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/CommandGuide/diagtool.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/CommandGuide/diagtool.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,52 @@
+diagtool - clang diagnostics tool
+=================================
+
+SYNOPSIS
+--------
+
+:program:`diagtool` *command* [*args*]
+
+DESCRIPTION
+-----------
+
+:program:`diagtool` is a combination of four tool for dealing with diagnostics in :program:`clang`.
+
+SUBCOMMANDS
+-----------
+
+:program:`diagtool` is separated into several subcommands each tailored to a
+different purpose. A brief summary of each command follows, with more detail in
+the sections that follow.
+
+  * :ref:`find_diagnostic_id` - Print the id of the given diagnostic.
+  * :ref:`list_warnings` - List warnings and their corresponding flags.
+  * :ref:`show_enabled` - Show which warnings are enabled for a given command line.
+  * :ref:`tree` - Show warning flags in a tree view.
+
+.. _find_diagnostic_id:
+
+find-diagnostic-id
+~~~~~~~~~~~~~~~~~~
+
+:program:`diagtool` find-diagnostic-id *diagnostic-name*
+
+.. _list_warnings:
+
+list-warnings
+~~~~~~~~~~~~~
+
+:program:`diagtool` list-warnings
+
+.. _show_enabled:
+
+show-enabled
+~~~~~~~~~~~~
+
+:program:`diagtool` show-enabled [*options*] *filename ...*
+
+.. _tree:
+
+tree
+~~~~
+
+:program:`diagtool` tree [*diagnostic-group*]

Added: www-releases/trunk/7.0.0/tools/clang/docs/_sources/CommandGuide/index.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/CommandGuide/index.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/CommandGuide/index.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/CommandGuide/index.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,18 @@
+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
+   diagtool

Added: www-releases/trunk/7.0.0/tools/clang/docs/_sources/ControlFlowIntegrity.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/ControlFlowIntegrity.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/ControlFlowIntegrity.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/ControlFlowIntegrity.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,343 @@
+======================
+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.
+  -  ``-fsanitize=cfi-mfcall``: Indirect call via a member function pointer 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 or types with public :doc:`LTO
+visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin``
+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 or types with public :doc:`LTO
+visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin``
+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 or types with public :doc:`LTO
+visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin``
+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-generalize-pointers``
+--------------------------------------------
+
+Mismatched pointer types are a common cause of cfi-icall check failures.
+Translation units compiled with the ``-fsanitize-cfi-icall-generalize-pointers``
+flag relax pointer type checking for call sites in that translation unit,
+applied across all functions compiled with ``-fsanitize=cfi-icall``.
+
+Specifically, pointers in return and argument types are treated as equivalent as
+long as the qualifiers for the type they point to match. For example, ``char*``,
+``char**``, and ``int*`` are considered equivalent types. However, ``char*`` and
+``const char*`` are considered separate types.
+
+``-fsanitize-cfi-icall-generalize-pointers`` is not compatible with
+``-fsanitize-cfi-cross-dso``.
+
+
+``-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.
+
+Member Function Pointer Call Checking
+=====================================
+
+This scheme checks that indirect calls via a member function pointer
+take place using an object of the correct dynamic type. Specifically, we
+check that the dynamic type of the member function referenced by the member
+function pointer matches the "function pointer" part of the member function
+pointer, and that the member function's class type is related to the base
+type of the member function. This CFI scheme can be enabled on its own using
+``-fsanitize=cfi-mfcall``.
+
+The compiler will only emit a full CFI check if the member function pointer's
+base type is complete. This is because the complete definition of the base
+type contains information that is necessary to correctly compile the CFI
+check. To ensure that the compiler always emits a full CFI check, it is
+recommended to also pass the flag ``-fcomplete-member-pointers``, which
+enables a non-conforming language extension that requires member pointer
+base types to be complete if they may be used for a call.
+
+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 or types with public :doc:`LTO
+visibility <LTOVisibility>`, must be compiled with ``-flto`` or ``-flto=thin``
+enabled and be statically linked into the program.
+
+This scheme is currently not compatible with cross-DSO CFI or the
+Microsoft ABI.
+
+.. _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. Specific CFI modes can be be specified using ``[section]``
+headers.
+
+.. code-block:: bash
+
+    # Suppress all CFI 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::*
+    # Disable only unrelated cast checks for this function
+    [cfi-unrelated-cast]
+    fun:*UnrelatedCast*
+    # Disable CFI call checks for this function without affecting cast checks
+    [cfi-vcall|cfi-nvcall|cfi-icall]
+    fun:*BadCall*
+
+
+.. _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/7.0.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/ControlFlowIntegrityDesign.rst.txt Wed Sep 19 02:40:08 2018
@@ -0,0 +1,655 @@
+===========================================
+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: http://itanium-cxx-abi.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, void *DiagData)
+
+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 reports an error if the type is unknown, or if the
+check fails. Depending on the values of compiler flags
+``-fsanitize-trap`` and ``-fsanitize-recover``, this function may
+print an error, abort and/or return to the caller. ``DiagData`` is an
+opaque pointer to the diagnostic information about the error, or
+``null`` if the caller does not provide this information.
+
+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 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 a runtime support library as
+
+.. code-block:: none
+
+  void __cfi_slowpath(uint64 CallSiteTypeId, void *TargetAddr)
+  void __cfi_slowpath_diag(uint64 CallSiteTypeId, void *TargetAddr, void *DiagData)
+
+These functions loads a shadow value for ``TargetAddr``, finds the
+address of ``__cfi_check`` as described above and calls
+that. ``DiagData`` is an opaque pointer to diagnostic data which is
+passed verbatim to ``__cfi_check``, and ``__cfi_slowpath`` passes
+``nullptr`` instead.
+
+Compiler-RT library contains reference implementations of slowpath
+functions, but they have unresolvable issues with correctness and
+performance in the handling of dlopen(). It is recommended that
+platforms provide their own implementations, usually as part of libc
+or libdl.
+
+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.
+
+Backward-edge CFI for return statements (RCFI)
+==============================================
+
+This section is a proposal. As of March 2017 it is not implemented.
+
+Backward-edge control flow (`RET` instructions) can be hijacked
+via overwriting the return address (`RA`) on stack.
+Various mitigation techniques (e.g. `SafeStack`_, `RFG`_, `Intel CET`_)
+try to detect or prevent `RA` corruption on stack.
+
+RCFI enforces the expected control flow in several different ways described below.
+RCFI heavily relies on LTO.
+
+Leaf Functions
+--------------
+If `f()` is a leaf function (i.e. it has no calls
+except maybe no-return calls) it can be called using a special calling convention
+that stores `RA` in a dedicated register `R` before the `CALL` instruction.
+`f()` does not spill `R` and does not use the `RET` instruction,
+instead it uses the value in `R` to `JMP` to `RA`.
+
+This flavour of CFI is *precise*, i.e. the function is guaranteed to return
+to the point exactly following the call.
+
+An alternative approach is to
+copy `RA` from stack to `R` in the first instruction of `f()`,
+then `JMP` to `R`.
+This approach is simpler to implement (does not require changing the caller)
+but weaker (there is a small window when `RA` is actually stored on stack).
+
+
+Functions called once
+---------------------
+Suppose `f()` is called in just one place in the program
+(assuming we can verify this in LTO mode).
+In this case we can replace the `RET` instruction with a `JMP` instruction
+with the immediate constant for `RA`.
+This will *precisely* enforce the return control flow no matter what is stored on stack.
+
+Another variant is to compare `RA` on stack with the known constant and abort
+if they don't match; then `JMP` to the known constant address.
+
+Functions called in a small number of call sites
+------------------------------------------------
+We may extend the above approach to cases where `f()`
+is called more than once (but still a small number of times).
+With LTO we know all possible values of `RA` and we check them
+one-by-one (or using binary search) against the value on stack.
+If the match is found, we `JMP` to the known constant address, otherwise abort.
+
+This protection is *near-precise*, i.e. it guarantees that the control flow will
+be transferred to one of the valid return addresses for this function,
+but not necessary to the point of the most recent `CALL`.
+
+General case
+------------
+For functions called multiple times a *return jump table* is constructed
+in the same manner as jump tables for indirect function calls (see above).
+The correct jump table entry (or it's index) is passed by `CALL` to `f()`
+(as an extra argument) and then spilled to stack.
+The `RET` instruction is replaced with a load of the jump table entry,
+jump table range check, and `JMP` to the jump table entry.
+
+This protection is also *near-precise*.
+
+Returns from functions called indirectly
+----------------------------------------
+
+If a function is called indirectly, the return jump table is constructed for the
+equivalence class of functions instead of a single function.
+
+Cross-DSO calls
+---------------
+Consider two instrumented DSOs, `A` and `B`. `A` defines `f()` and `B` calls it.
+
+This case will be handled similarly to the cross-DSO scheme using the slow path callback.
+
+Non-goals
+---------
+
+RCFI does not protect `RET` instructions:
+  * in non-instrumented DSOs,
+  * in instrumented DSOs for functions that are called from non-instrumented DSOs,
+  * embedded into other instructions (e.g. `0f4fc3 cmovg %ebx,%eax`).
+
+.. _SafeStack: https://clang.llvm.org/docs/SafeStack.html
+.. _RFG: http://xlab.tencent.com/en/2016/11/02/return-flow-guard
+.. _Intel CET: https://software.intel.com/en-us/blogs/2016/06/09/intel-release-new-technology-specifications-protect-rop-attacks
+
+Hardware support
+================
+
+We believe that the above design can be efficiently implemented in hardware.
+A single new instruction added to an ISA would allow to perform the forward-edge CFI check
+with fewer bytes per check (smaller code size overhead) and potentially more
+efficiently. The current software-only instrumentation requires at least
+32-bytes per check (on x86_64).
+A hardware instruction may probably be less than ~ 12 bytes.
+Such instruction would check that the argument pointer is in-bounds,
+and is properly aligned, and if the checks fail it will either trap (in monolithic scheme)
+or call the slow path function (cross-DSO scheme).
+The bit vector lookup is probably too complex for a hardware implementation.
+
+.. code-block:: none
+
+  //  This instruction checks that 'Ptr'
+  //   * is aligned by (1 << kAlignment) and
+  //   * is inside [kRangeBeg, kRangeBeg+(kRangeSize<<kAlignment))
+  //  and if the check fails it jumps to the given target (slow path).
+  //
+  // 'Ptr' is a register, pointing to the virtual function table
+  //    or to the function which we need to check. We may require an explicit
+  //    fixed register to be used.
+  // 'kAlignment' is a 4-bit constant.
+  // 'kRangeSize' is a ~20-bit constant.
+  // 'kRangeBeg' is a PC-relative constant (~28 bits)
+  //    pointing to the beginning of the allowed range for 'Ptr'.
+  // 'kFailedCheckTarget': is a PC-relative constant (~28 bits)
+  //    representing the target to branch to when the check fails.
+  //    If kFailedCheckTarget==0, the process will trap
+  //    (monolithic binary scheme).
+  //    Otherwise it will jump to a handler that implements `CFI_SlowPath`
+  //    (cross-DSO scheme).
+  CFI_Check(Ptr, kAlignment, kRangeSize, kRangeBeg, kFailedCheckTarget) {
+     if (Ptr < kRangeBeg ||
+         Ptr >= kRangeBeg + (kRangeSize << kAlignment) ||
+         Ptr & ((1 << kAlignment) - 1))
+           Jump(kFailedCheckTarget);
+  }
+
+An alternative and more compact encoding would not use `kFailedCheckTarget`,
+and will trap on check failure instead.
+This will allow us to fit the instruction into **8-9 bytes**.
+The cross-DSO checks will be performed by a trap handler and
+performance-critical ones will have to be black-listed and checked using the
+software-only scheme.
+
+Note that such hardware extension would be complementary to checks
+at the callee side, such as e.g. **Intel ENDBRANCH**.
+Moreover, CFI would have two benefits over ENDBRANCH: a) precision and b)
+ability to protect against invalid casts between polymorphic types.

Added: www-releases/trunk/7.0.0/tools/clang/docs/_sources/CrossCompilation.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/CrossCompilation.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/CrossCompilation.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/CrossCompilation.rst.txt Wed Sep 19 02:40:08 2018
@@ -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_64``, ``i386``, ``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/7.0.0/tools/clang/docs/_sources/DataFlowSanitizer.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/DataFlowSanitizer.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/DataFlowSanitizer.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/DataFlowSanitizer.rst.txt Wed Sep 19 02:40:08 2018
@@ -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/7.0.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.rst.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.rst.txt?rev=342530&view=auto
==============================================================================
--- www-releases/trunk/7.0.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.rst.txt (added)
+++ www-releases/trunk/7.0.0/tools/clang/docs/_sources/DataFlowSanitizerDesign.rst.txt Wed Sep 19 02:40:08 2018
@@ -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.




More information about the llvm-commits mailing list