samsonov added you to the CC list for the revision "Documentation for sanitizer
special case list".
Hi eugenis, silvas,
This documents the usage of -f(no)?sanitize-blacklist flags,
and the generic format of this file. Note, that although the original
name is "blacklist", we start to rename it into "special case list",
as newer tools (DataFlowSanitizer, which is under development) may use
to alter instrumentation instead of disabling it completely.
http://llvm-reviews.chandlerc.com/D1268
Files:
docs/UsersManual.rst
docs/SanitizerSpecialCaseList.rst
docs/index.rst
docs/AddressSanitizer.rst
Index: docs/UsersManual.rst
===================================================================
--- docs/UsersManual.rst
+++ docs/UsersManual.rst
@@ -940,6 +940,15 @@
it is of the wrong dynamic type, or that its lifetime has not
begun or has ended. Incompatible with ``-fno-rtti``.
+ You can turn off or modify checks for certain source files, functions
+ or even variables by providing a special file:
+
+ - ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify
+ sanitizer checks for objects listed in the file. See
+ :doc:`SanitizerSpecialCaseList` for file format description.
+ - ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
+ specified earlier in the command line.
+
Experimental features of AddressSanitizer (not ready for widespread
use, require explicit ``-fsanitize=address``):
Index: docs/SanitizerSpecialCaseList.rst
===================================================================
--- /dev/null
+++ docs/SanitizerSpecialCaseList.rst
@@ -0,0 +1,49 @@
+===========================
+Sanitizer special case list
+===========================
+
+.. contents::
+ :local:
+
+Goal
+====
+
+User of sanitizer tools, such as :doc:`AddressSanitizer`,
:doc:`ThreadSanitizer`
+or :doc:`MemorySanitizer` may want to disable or alter some checks for
+certain objects to:
+
+* speedup hot function, which is known to be correct;
+* ignore a function that does some low-level magic (e.g. walks through the
+ thread stack, bypassing the frame boundaries);
+* ignore a known problem.
+
+To achieve this, user may provide a file listing the objects he wants to
+ignore, and provide it to clang at compile-time.
+
+Generally, the use of this file is **discouraged**, in most cases it's better
+to fix the reported issue in the source code.
+
+Format
+======
+
+Each special case list entry occupies a single line.
+
+.. code-block:: bash
+
+ # Empty lines, and lines starting with # are ignored.
+ # Turn off checks for the source file:
+ src:/path/to/source/file.c
+ # Turn off checks for a particular functions (use mangled names):
+ fun:MyFooBar
+ fun:_Z8MyFooBarv
+ # Wildcards are supported:
+ src:bad/sources/*
+ fun:*BadFunction*
+
+Some sanitizer tools may introduce custom entry types - see the tool-specific
docs.
+
+Usage
+=====
+
+Create a file and provide it to the compiler using ``-fsanitize-blacklist``
flag.
+See :doc:`UsersManual` for details.
Index: docs/index.rst
===================================================================
--- docs/index.rst
+++ docs/index.rst
@@ -21,6 +21,7 @@
AddressSanitizer
ThreadSanitizer
MemorySanitizer
+ SanitizerSpecialCaseList
Modules
FAQ
Index: docs/AddressSanitizer.rst
===================================================================
--- docs/AddressSanitizer.rst
+++ docs/AddressSanitizer.rst
@@ -126,6 +126,24 @@
you should set environment variable
``ASAN_OPTIONS=check_initialization_order=1``.
+Blacklist
+---------
+
+You may use sanitizer special case list to disable AddressSanizier checks for
+certain source files, functions and global variables. See
+:doc:`SanitizerSpecialCaseList` for general file format description.
+AddressSanitizer-specific entry formats are:
+
+.. code-block:: bash
+
+ # Disable checks for globals with certain names or types:
+ global:bad_array
+ type:*Namespace::BadClassName*
+ # Disable initialization-order checks for globals:
+ global:bad_init_global=init
+ type:*Namespace::BadInitClassName*=init
+ src:bad/init/files/*=init
+
Supported Platforms
===================
Index: docs/UsersManual.rst
===================================================================
--- docs/UsersManual.rst
+++ docs/UsersManual.rst
@@ -940,6 +940,15 @@
it is of the wrong dynamic type, or that its lifetime has not
begun or has ended. Incompatible with ``-fno-rtti``.
+ You can turn off or modify checks for certain source files, functions
+ or even variables by providing a special file:
+
+ - ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify
+ sanitizer checks for objects listed in the file. See
+ :doc:`SanitizerSpecialCaseList` for file format description.
+ - ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
+ specified earlier in the command line.
+
Experimental features of AddressSanitizer (not ready for widespread
use, require explicit ``-fsanitize=address``):
Index: docs/SanitizerSpecialCaseList.rst
===================================================================
--- /dev/null
+++ docs/SanitizerSpecialCaseList.rst
@@ -0,0 +1,49 @@
+===========================
+Sanitizer special case list
+===========================
+
+.. contents::
+ :local:
+
+Goal
+====
+
+User of sanitizer tools, such as :doc:`AddressSanitizer`, :doc:`ThreadSanitizer`
+or :doc:`MemorySanitizer` may want to disable or alter some checks for
+certain objects to:
+
+* speedup hot function, which is known to be correct;
+* ignore a function that does some low-level magic (e.g. walks through the
+ thread stack, bypassing the frame boundaries);
+* ignore a known problem.
+
+To achieve this, user may provide a file listing the objects he wants to
+ignore, and provide it to clang at compile-time.
+
+Generally, the use of this file is **discouraged**, in most cases it's better
+to fix the reported issue in the source code.
+
+Format
+======
+
+Each special case list entry occupies a single line.
+
+.. code-block:: bash
+
+ # Empty lines, and lines starting with # are ignored.
+ # Turn off checks for the source file:
+ src:/path/to/source/file.c
+ # Turn off checks for a particular functions (use mangled names):
+ fun:MyFooBar
+ fun:_Z8MyFooBarv
+ # Wildcards are supported:
+ src:bad/sources/*
+ fun:*BadFunction*
+
+Some sanitizer tools may introduce custom entry types - see the tool-specific docs.
+
+Usage
+=====
+
+Create a file and provide it to the compiler using ``-fsanitize-blacklist`` flag.
+See :doc:`UsersManual` for details.
Index: docs/index.rst
===================================================================
--- docs/index.rst
+++ docs/index.rst
@@ -21,6 +21,7 @@
AddressSanitizer
ThreadSanitizer
MemorySanitizer
+ SanitizerSpecialCaseList
Modules
FAQ
Index: docs/AddressSanitizer.rst
===================================================================
--- docs/AddressSanitizer.rst
+++ docs/AddressSanitizer.rst
@@ -126,6 +126,24 @@
you should set environment variable
``ASAN_OPTIONS=check_initialization_order=1``.
+Blacklist
+---------
+
+You may use sanitizer special case list to disable AddressSanizier checks for
+certain source files, functions and global variables. See
+:doc:`SanitizerSpecialCaseList` for general file format description.
+AddressSanitizer-specific entry formats are:
+
+.. code-block:: bash
+
+ # Disable checks for globals with certain names or types:
+ global:bad_array
+ type:*Namespace::BadClassName*
+ # Disable initialization-order checks for globals:
+ global:bad_init_global=init
+ type:*Namespace::BadInitClassName*=init
+ src:bad/init/files/*=init
+
Supported Platforms
===================
_______________________________________________
cfe-commits mailing list
cfe-commits@cs.uiuc.edu
http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
