[clang] 1dc005a - Add documentation for -fsanitize-address-use-after-return.

[Kevin Athey via cfe-commits]

Author: Kevin Athey
Date: 2021-07-08T16:44:08-07:00
New Revision: 1dc005aa7dc51131515894cbd34f27d6b361f23e

URL: https://github.com/llvm/llvm-project/commit/1dc005aa7dc51131515894cbd34f27d6b361f23e
DIFF: https://github.com/llvm/llvm-project/commit/1dc005aa7dc51131515894cbd34f27d6b361f23e.diff

LOG: Add documentation for -fsanitize-address-use-after-return.

for issue: https://github.com/google/sanitizers/issues/1394

Reviewed By: vitalybuka

Differential Revision: https://reviews.llvm.org/D104155

Added: 
    

Modified: 
    clang/docs/AddressSanitizer.rst
    clang/docs/UsersManual.rst
    clang/include/clang/Driver/Options.td

Removed: 
    


################################################################################
diff  --git a/clang/docs/AddressSanitizer.rst b/clang/docs/AddressSanitizer.rst
index 865468342404..14f3938496c3 100644
--- a/clang/docs/AddressSanitizer.rst
+++ b/clang/docs/AddressSanitizer.rst
@@ -14,8 +14,9 @@ following types of bugs:
 
 * Out-of-bounds accesses to heap, stack and globals
 * Use-after-free
-* Use-after-return (runtime flag `ASAN_OPTIONS=detect_stack_use_after_return=1`)
-* Use-after-scope (clang flag `-fsanitize-address-use-after-scope`)
+* Use-after-return (clang flag ``-fsanitize-address-use-after-return=(never|runtime|always)`` default: ``runtime``)
+    * Enable ``runtime`` with: ``ASAN_OPTIONS=detect_stack_use_after_return=1``
+* Use-after-scope (clang flag ``-fsanitize-address-use-after-scope``)
 * Double-free, invalid free
 * Memory leaks (experimental)
 
@@ -136,6 +137,26 @@ you should set environment variable
 
 Note that this option is not supported on macOS.
 
+Stack Use After Return (UAR)
+----------------------------
+
+AddressSanitizer can optionally detect stack use after return problems.
+This is available by default, or explicitly
+(``-fsanitize-address-use-after-return=runtime``).
+To enable this check at runtime, set the environment variable
+``ASAN_OPTIONS=detect_stack_use_after_return=1``.
+
+Enabling this check (``-fsanitize-address-use-after-return=always``) will
+reduce code size.  The code size may be reduced further by completely
+eliminating this check (``-fsanitize-address-use-after-return=never``).
+
+To summarize: ``-fsanitize-address-use-after-return=<mode>``
+  * ``never``: Completely disables detection of UAR errors (reduces code size).
+  * ``runtime``: Adds the code for detection, but must be enabled via the
+    runtime environment (``ASAN_OPTIONS=detect_stack_use_after_return=1``).
+  * ``always``: Enables detection of UAR errors in all cases. (reduces code
+    size, but not as much as ``never``).
+
 Memory leak detection
 ---------------------
 

diff  --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index 9e8bac635337..57d53415c580 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -3744,6 +3744,8 @@ Execute ``clang-cl /?`` to see a list of supported options:
                               Enable linker dead stripping of globals in AddressSanitizer
       -fsanitize-address-poison-custom-array-cookie
                               Enable poisoning array cookies when using custom operator new[] in AddressSanitizer
+      -fsanitize-address-use-after-return=<mode>
+                              Select the mode of detecting stack use-after-return in AddressSanitizer: never | runtime (default) | always
       -fsanitize-address-use-after-scope
                               Enable use-after-scope detection in AddressSanitizer
       -fsanitize-address-use-odr-indicator

diff  --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td
index c2b21d985124..c15690d44884 100644
--- a/clang/include/clang/Driver/Options.td
+++ b/clang/include/clang/Driver/Options.td
@@ -1584,7 +1584,7 @@ def sanitize_address_use_after_return_EQ
   : Joined<["-"], "fsanitize-address-use-after-return=">,
     MetaVarName<"<mode>">,
     Flags<[CC1Option]>,
-    HelpText<"Select the mode of detecting stack use-after-return in AddressSanitizer">,
+    HelpText<"Select the mode of detecting stack use-after-return in AddressSanitizer: never | runtime (default) | always">,
     Group<f_clang_Group>,
     Values<"never,runtime,always">,
     NormalizedValuesScope<"llvm::AsanDetectStackUseAfterReturnMode">,