forked from OSchip/llvm-project
[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
llvm-svn: 240725
This commit is contained in:
Anna Zaks
parent
a16075cfc9
commit
8264a8cdbc
|
|
@ -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=symbolize=0``):
|
|||
Note that on OS X you may need to run ``dsymutil`` on your binary to have the
|
||||
file\:line info in the AddressSanitizer reports.
|
||||
|
||||
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
|
||||
=================
|
||||
|
||||
``__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``.
|
||||
|
||||
Note that this option is not supported on OS X.
|
||||
|
||||
Memory leak detection
|
||||
---------------------
|
||||
|
||||
For more information on leak detector in AddressSanitizer, see
|
||||
:doc:`LeakSanitizer`. The leak detection is turned on by default on Linux;
|
||||
however, it is not yet supported on other platforms.
|
||||
|
||||
Issue Suppression
|
||||
=================
|
||||
|
||||
AddressSanitizer is not expected to produce false positives. If you see one,
|
||||
look again; most likely it is a true positive!
|
||||
|
||||
Suppressing Reports in External Libraries
|
||||
-----------------------------------------
|
||||
Runtime interposition allows AddressSanitizer to find bugs in code that is
|
||||
not being recompiled. If you run into an issue in external libraries, we
|
||||
recommend immediately reporting it to the library maintainer so that it
|
||||
gets addressed. However, you can use the following suppression mechanism
|
||||
to unblock yourself and continue on with the testing. This suppression
|
||||
mechanism should only be used for suppressing issues in external code; it
|
||||
does not work on code recompiled with AddressSanitizer. To suppress errors
|
||||
in external libraries, set the ``ASAN_OPTIONS`` environment variable to point
|
||||
to a suppression file. You can either specify the full path to the file or the
|
||||
path of the file relative to the location of your executable.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ASAN_OPTIONS=suppressions=MyASan.supp
|
||||
|
||||
Use the following format to specify the names of the functions or libraries
|
||||
you want to suppress. You can see these in the error report. Remember that
|
||||
the narrower the scope of the suppression, the more bugs you will be able to
|
||||
catch.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
interceptor_via_fun:NameOfCFunctionToSuppress
|
||||
interceptor_via_fun:-[ClassName objCMethodToSuppress:]
|
||||
interceptor_via_lib:NameOfTheLibraryToSuppress
|
||||
|
||||
Conditional Compilation with ``__has_feature(address_sanitizer)``
|
||||
-----------------------------------------------------------------
|
||||
|
||||
In some cases one may need to execute different code depending on whether
|
||||
AddressSanitizer is enabled.
|
||||
|
|
@ -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 files or with certain global variables.
|
|||
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
|
||||
==============
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue