Updates to user's manual and release notes for -fsanitize= options.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@167479 91177308-0d34-0410-b5e6-96231b3b80d8

2 files changed, 66 insertions, 31 deletions

diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html
index 78108fb9db..8a195f0b83 100644
--- a/docs/ReleaseNotes.html
+++ b/docs/ReleaseNotes.html
@@ -170,11 +170,14 @@ int f(vector<map<int, double>>);
 
   </li>
 
-  <li>Clang's <tt>-fcatch-undefined-behavior</tt> option has grown the ability
-  to check for several new types of undefined behavior.
+  <li>Clang's <tt>-fcatch-undefined-behavior</tt> option has been renamed to
+  <tt>-fsanitize=undefined</tt> and has grown the ability to check for several
+  new types of undefined behavior. See the Users Manual for more information.
 
   <!-- Flesh this out prior to release. -->
 
+  <!-- Document renaming of -faddress-sanitizer and -fthread-sanitizer. -->
+
   </li>
 
 </ul>
diff --git a/docs/UsersManual.html b/docs/UsersManual.html
index 50a373886a..35fc5dca33 100644
--- a/docs/UsersManual.html
+++ b/docs/UsersManual.html
@@ -874,45 +874,77 @@ likely to affect PCH files that reference a large number of headers.</p>
 
 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 <dl>
-<dt id="opt_fcatch-undefined-behavior"><b>-fcatch-undefined-behavior</b>: Turn
-on runtime code generation to check for undefined behavior.</dt>
+<dt id="opt_fsanitize"><b>-fsanitize=check1,check2</b>: Turn on runtime checks
+for various forms of undefined behavior.</dt>
+
+<dd>This option controls whether Clang adds runtime checks for various forms of
+undefined behavior, and is disabled by default. If a check fails, a diagnostic
+message is produced at runtime explaining the problem. The main checks are:
 
-<dd>This option, which defaults to off, controls whether or not Clang
-adds runtime checks for undefined runtime behavior.  If a check fails,
-<tt>__builtin_trap()</tt> is used to indicate failure.
-The currently implemented checks include:
 <ul>
-<li>Subscripting where the static type of one operand is a variable
-    which is decayed from an array type and the other operand is
-    greater than the size of the array or less than zero.</li>
-<li>Shift operators where the amount shifted is greater or equal to the
-    promoted bit-width of the left-hand-side or less than zero.</li>
-<li>If control flow reaches __builtin_unreachable.</li>
-<li>Reads and writes for objects which are inappropriately aligned or are not
-    large enough (in cases where the size can be determined).
-<li>Signed integer overflow, including all the checks added by <tt>-ftrapv</tt>
-    and also checking for signed left shift overflow.</li>
-<li>Binding a reference to a storage location which is not of an appropriate
-    alignment or size (in cases where the size can be determined), or binding
-    a reference to an empty glvalue (a dereferenced null pointer).
-<li>Class member access or member function call where the <tt>this</tt>
-    pointer is not of an appropriate alignment or size (in cases where the size
-    can be determined), or where it is null.</li>
+<li id="opt_fsanitize_address"><tt>-fsanitize=address</tt>:
+    <a href="AddressSanitizer.html">AddressSanitizer</a>, a memory error
+    detector.</li>
+<li id="opt_fsanitize_thread"><tt>-fsanitize=thread</tt>:
+    <a href="ThreadSanitizer.html">ThreadSanitizer</a>, an <em>experimental</em>
+    data race detector.  Not ready for widespread use.</li>
+<li id="opt_fsanitize_undefined"><tt>-fsanitize=undefined</tt>:
+    Enables all the checks listed below.</li>
 </ul>
 
-<p>The sizes of objects are determined using <tt>__builtin_object_size</tt>, and
-consequently may be able to detect more problems at higher optimization levels.
-Bit-fields and vectors are not yet checked.</p>
+The following more fine-grained checks are also available:
 
+<ul>
+<li id="opt_fsanitize_alignment"><tt>-fsanitize=alignment</tt>:
+    Use of a misaligned pointer or creation of a misaligned reference.</li>
+<li id="opt_fsanitize_divide-by-zero"><tt>-fsanitize=divide-by-zero</tt>:
+    Division by zero.</li>
+<li id="opt_fsanitize_float-cast-overflow"><tt>-fsanitize=float-cast-overflow</tt>:
+    Conversion to, from, or between floating-point types which would overflow
+    the destination.</li>
+<li id="opt_fsanitize_null"><tt>-fsanitize=null</tt>:
+    Use of a null pointer or creation of a null reference.</li>
+<li id="opt_fsanitize_object-size"><tt>-fsanitize=object-size</tt>:
+    An attempt to use bytes which the optimizer can determine are not part of
+    the object being accessed.
+    The sizes of objects are determined using <tt>__builtin_object_size</tt>, and
+    consequently may be able to detect more problems at higher optimization
+    levels.</li>
+<li id="opt_fsanitize_return"><tt>-fsanitize=return</tt>:
+    In C++, reaching the end of a value-returning function without returning a
+    value.</li>
+<li id="opt_fsanitize_shift"><tt>-fsanitize=shift</tt>:
+    Shift operators where the amount shifted is greater or equal to the
+    promoted bit-width of the left hand side or less than zero, or where
+    the left hand side is negative. For a signed left shift, also checks
+    for signed overflow in C, and for unsigned overflow in C++.</li>
+<li id="opt_fsanitize_signed-integer-overflow"><tt>-fsanitize=signed-integer-overflow</tt>:
+    Signed integer overflow, including all the checks added by <tt>-ftrapv</tt>,
+    and checking for overflow in signed division (<tt>INT_MIN / -1</tt>).</li>
+<li id="opt_fsanitize_unreachable"><tt>-fsanitize=unreachable</tt>:
+    If control flow reaches __builtin_unreachable.</li>
+<li id="opt_fsanitize_vla-bound"><tt>-fsanitize=vla-bound</tt>:
+    A variable-length array whose bound does not evaluate to a positive value.</li>
+<li id="opt_fsanitize_vptr"><tt>-fsanitize=vptr</tt>:
+    Use of an object whose vptr indicates that it is of the wrong dynamic type,
+    or that its lifetime has not begun or has ended. Incompatible with
+    <tt>-fno-rtti</tt>.</li>
+</ul>
+
+The <tt>-fsanitize=</tt> argument must also be provided when linking, in order
+to link to the appropriate runtime library. It is not possible to combine the
+<tt>-fsanitize=address</tt> and <tt>-fsanitize=thread</tt> checkers in the same
+program.
 </dd>
 
 <dt id="opt_faddress-sanitizer"><b>-f[no-]address-sanitizer</b>:
-Turn on <a href="AddressSanitizer.html">AddressSanitizer</a>,
-a memory error detector.
+Deprecated synonym for <a href="#opt_fsanitize_address"><tt>-f[no-]sanitize=address</tt></a>.
 
 <dt id="opt_fthread-sanitizer"><b>-f[no-]thread-sanitizer</b>:
-Turn on ThreadSanitizer, an <em>experimental</em> data race detector.
-Not ready for widespread use.
+Deprecated synonym for <a href="#opt_fsanitize_address"><tt>-f[no-]sanitize=thread</tt></a>.
+
+<dt id="opt_fcatch-undefined-behavior"><b>-fcatch-undefined-behavior</b>:
+Deprecated synonym for <a href="#opt_fsanitize_undefined"><tt>-fsanitize=undefined</tt></a>.
 
 <dt id="opt_fno-assume-sane-operator-new"><b>-fno-assume-sane-operator-new</b>:
 Don't assume that the C++'s new operator is sane.</dt>