r240725 - [docs] Several updates to the Address Sanitizer webpage.
Anna Zaks
ganna at apple.com
Thu Jun 25 16:36:45 PDT 2015
Author: zaks
Date: Thu Jun 25 18:36:44 2015
New Revision: 240725
URL: http://llvm.org/viewvc/llvm-project?rev=240725&view=rev
Log:
[docs] Several updates to the Address Sanitizer webpage.
- Added the description of the interceptor suppression.
- Re-organized a bit: grouped a few things under the Issue Suppression
section, grouped IOC and leaks under a section, placed symbolication
info into Symbolizing the Reports section..
- In supported platforms: "MacOS" -> "OS X"; added "iOS Simulator"
- Added a paragraph to the Usage section describing when DYLD_INSERT_LIBRARIES
might need to be used.
- "attribute((no_sanitize_address))" -> "__attribute__((no_sanitize("address")))"
- Updated Leak Sanitizer page with most up to date info.
....
http://reviews.llvm.org/D10559
Modified:
cfe/trunk/docs/AddressSanitizer.rst
cfe/trunk/docs/LeakSanitizer.rst
Modified: cfe/trunk/docs/AddressSanitizer.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/AddressSanitizer.rst?rev=240725&r1=240724&r2=240725&view=diff
==============================================================================
--- cfe/trunk/docs/AddressSanitizer.rst (original)
+++ cfe/trunk/docs/AddressSanitizer.rst Thu Jun 25 18:36:44 2015
@@ -60,7 +60,28 @@ or:
% clang -g -fsanitize=address example_UseAfterFree.o
If a bug is detected, the program will print an error message to stderr and
-exit with a non-zero exit code. To make AddressSanitizer symbolize its output
+exit with a non-zero exit code. AddressSanitizer exits on the first detected error.
+This is by design:
+
+* This approach allows AddressSanitizer to produce faster and smaller generated code
+ (both by ~5%).
+* Fixing bugs becomes unavoidable. AddressSanitizer does not produce
+ false alarms. Once a memory corruption occurs, the program is in an inconsistent
+ state, which could lead to confusing results and potentially misleading
+ subsequent reports.
+
+If your process is sandboxed and you are running on OS X 10.10 or earlier, you
+will need to set ``DYLD_INSERT_LIBRARIES`` environment variable and point it to
+the ASan library that is packaged with the compiler used to build the
+executable. (You can find the library by searching for dynamic libraries with
+``asan`` in their name.) If the environment variable is not set, the process will
+try to re-exec. Also keep in mind that when moving the executable to another machine,
+the ASan library will also need to be copied over.
+
+Symbolizing the Reports
+=========================
+
+To make AddressSanitizer symbolize its output
you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to
the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your
``$PATH``):
@@ -100,14 +121,63 @@ force disabled by setting ``ASAN_OPTIONS
Note that on OS X you may need to run ``dsymutil`` on your binary to have the
file\:line info in the AddressSanitizer reports.
-AddressSanitizer exits on the first detected error. This is by design.
-One reason: it makes the generated code smaller and faster (both by
-~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind,
-it is often the case that users treat Valgrind warnings as false
-positives (which they are not) and don't fix them.
+Additional Checks
+=================
+
+Initialization order checking
+-----------------------------
+
+AddressSanitizer can optionally detect dynamic initialization order problems,
+when initialization of globals defined in one translation unit uses
+globals defined in another translation unit. To enable this check at runtime,
+you should set environment variable
+``ASAN_OPTIONS=check_initialization_order=1``.
+
+Note that this option is not supported on OS X.
+
+Memory leak detection
+---------------------
+
+For more information on leak detector in AddressSanitizer, see
+:doc:`LeakSanitizer`. The leak detection is turned on by default on Linux;
+however, it is not yet supported on other platforms.
+
+Issue Suppression
+=================
+
+AddressSanitizer is not expected to produce false positives. If you see one,
+look again; most likely it is a true positive!
+
+Suppressing Reports in External Libraries
+-----------------------------------------
+Runtime interposition allows AddressSanitizer to find bugs in code that is
+not being recompiled. If you run into an issue in external libraries, we
+recommend immediately reporting it to the library maintainer so that it
+gets addressed. However, you can use the following suppression mechanism
+to unblock yourself and continue on with the testing. This suppression
+mechanism should only be used for suppressing issues in external code; it
+does not work on code recompiled with AddressSanitizer. To suppress errors
+in external libraries, set the ``ASAN_OPTIONS`` environment variable to point
+to a suppression file. You can either specify the full path to the file or the
+path of the file relative to the location of your executable.
+
+.. code-block:: bash
+
+ ASAN_OPTIONS=suppressions=MyASan.supp
+
+Use the following format to specify the names of the functions or libraries
+you want to suppress. You can see these in the error report. Remember that
+the narrower the scope of the suppression, the more bugs you will be able to
+catch.
-``__has_feature(address_sanitizer)``
-------------------------------------
+.. code-block:: bash
+
+ interceptor_via_fun:NameOfCFunctionToSuppress
+ interceptor_via_fun:-[ClassName objCMethodToSuppress:]
+ interceptor_via_lib:NameOfTheLibraryToSuppress
+
+Conditional Compilation with ``__has_feature(address_sanitizer)``
+-----------------------------------------------------------------
In some cases one may need to execute different code depending on whether
AddressSanitizer is enabled.
@@ -122,28 +192,19 @@ this purpose.
# endif
#endif
-``__attribute__((no_sanitize_address))``
------------------------------------------------
+Disabling Instrumentation with ``__attribute__((no_sanitize("address")))``
+--------------------------------------------------------------------------
Some code should not be instrumented by AddressSanitizer. One may use the
-function attribute
-:ref:`no_sanitize_address <langext-address_sanitizer>`
-(or a deprecated synonym `no_address_safety_analysis`)
-to disable instrumentation of a particular function. This attribute may not be
-supported by other compilers, so we suggest to use it together with
-``__has_feature(address_sanitizer)``.
+function attribute ``__attribute__((no_sanitize("address")))``
+(which has deprecated synonyms
+:ref:`no_sanitize_address <langext-address_sanitizer>` and
+`no_address_safety_analysis`) to disable instrumentation of a particular
+function. This attribute may not be supported by other compilers, so we suggest
+to use it together with ``__has_feature(address_sanitizer)``.
-Initialization order checking
------------------------------
-
-AddressSanitizer can optionally detect dynamic initialization order problems,
-when initialization of globals defined in one translation unit uses
-globals defined in another translation unit. To enable this check at runtime,
-you should set environment variable
-``ASAN_OPTIONS=check_initialization_order=1``.
-
-Blacklist
----------
+Suppressing Errors in Recompiled Code (Blacklist)
+-------------------------------------------------
AddressSanitizer supports ``src`` and ``fun`` entity types in
:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
@@ -172,24 +233,6 @@ problems happening in certain source fil
type:*BadInitClassSubstring*=init
src:bad/init/files/*=init
-Memory leak detection
----------------------
-
-For the experimental memory leak detector in AddressSanitizer, see
-:doc:`LeakSanitizer`.
-
-Supported Platforms
-===================
-
-AddressSanitizer is supported on
-
-* Linux i386/x86\_64 (tested on Ubuntu 12.04);
-* MacOS 10.6 - 10.9 (i386/x86\_64).
-* Android ARM
-* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
-
-Ports to various other platforms are in progress.
-
Limitations
===========
@@ -202,6 +245,19 @@ Limitations
usually expected.
* Static linking is not supported.
+Supported Platforms
+===================
+
+AddressSanitizer is supported on:
+
+* Linux i386/x86\_64 (tested on Ubuntu 12.04)
+* OS X 10.7 - 10.11 (i386/x86\_64)
+* iOS Simulator
+* Android ARM
+* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
+
+Ports to various other platforms are in progress.
+
Current Status
==============
Modified: cfe/trunk/docs/LeakSanitizer.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LeakSanitizer.rst?rev=240725&r1=240724&r2=240725&view=diff
==============================================================================
--- cfe/trunk/docs/LeakSanitizer.rst (original)
+++ cfe/trunk/docs/LeakSanitizer.rst Thu Jun 25 18:36:44 2015
@@ -17,7 +17,8 @@ only, at a minimal performance cost.
Current status
==============
-LeakSanitizer is experimental and supported only on x86\_64 Linux.
+LeakSanitizer is turned on by default, but it is only supported on x86\_64
+Linux.
The combined mode has been tested on fairly large software projects. The
stand-alone mode has received much less testing.
More information about the cfe-commits
mailing list