[PATCH] Documentation for sanitizer special case list

Alexey Samsonov samsonov at google.com
Fri Aug 2 05:42:27 PDT 2013

  Address comments by eugenis.

Hi eugenis, silvas,




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/MemorySanitizer.rst
--- docs/MemorySanitizer.rst
+++ docs/MemorySanitizer.rst
@@ -93,6 +93,14 @@
 ``__has_feature(memory_sanitizer)``. Note: currently, this attribute will be
 lost if the function is inlined.
+You may use :doc:`SanitizerSpecialCaseList` to relax MemorySanitizer checks
+for certain functions and source files. All "Use of uninitialized value"
+warnings will be suppressed and all values loaded from memory will be
+considered fully initialized.
 Origin Tracking
Index: docs/SanitizerSpecialCaseList.rst
--- /dev/null
+++ docs/SanitizerSpecialCaseList.rst
@@ -0,0 +1,50 @@
+Sanitizer special case list
+.. contents::
+   :local:
+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.
+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 (use absolute path or path relative
+    # to the current working directory):
+    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.
+Create a file and provide it to the compiler using ``-fsanitize-blacklist`` flag.
+See :doc:`UsersManual` for details.
Index: docs/AddressSanitizer.rst
--- docs/AddressSanitizer.rst
+++ docs/AddressSanitizer.rst
@@ -126,6 +126,24 @@
 you should set environment variable
+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/ThreadSanitizer.rst
--- docs/ThreadSanitizer.rst
+++ docs/ThreadSanitizer.rst
@@ -97,6 +97,12 @@
 ``__has_feature(thread_sanitizer)``. Note: currently, this attribute will be
 lost if the function is inlined.
+You may use :doc:`SanitizerSpecialCaseList` to disable ThreadSanitizer checks
+for certain functions and source files. Data race reports will be suppressed.
Index: docs/index.rst
--- docs/index.rst
+++ docs/index.rst
@@ -21,6 +21,7 @@
+   SanitizerSpecialCaseList
-------------- next part --------------
A non-text attachment was scrubbed...
Name: D1268.2.patch
Type: text/x-patch
Size: 4820 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130802/981d19d4/attachment.bin>

More information about the cfe-commits mailing list