r187871 - Documentation for sanitizer special case list format and -f(no-)?sanitize-blacklist flag
Alexey Samsonov
samsonov at google.com
Wed Aug 7 01:23:33 PDT 2013
Author: samsonov
Date: Wed Aug 7 03:23:32 2013
New Revision: 187871
URL: http://llvm.org/viewvc/llvm-project?rev=187871&view=rev
Log:
Documentation for sanitizer special case list format and -f(no-)?sanitize-blacklist flag
Added:
cfe/trunk/docs/SanitizerSpecialCaseList.rst
Modified:
cfe/trunk/docs/AddressSanitizer.rst
cfe/trunk/docs/MemorySanitizer.rst
cfe/trunk/docs/ThreadSanitizer.rst
cfe/trunk/docs/UsersManual.rst
cfe/trunk/docs/index.rst
Modified: cfe/trunk/docs/AddressSanitizer.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/AddressSanitizer.rst?rev=187871&r1=187870&r2=187871&view=diff
==============================================================================
--- cfe/trunk/docs/AddressSanitizer.rst (original)
+++ cfe/trunk/docs/AddressSanitizer.rst Wed Aug 7 03:23:32 2013
@@ -126,6 +126,36 @@ globals defined in another translation u
you should set environment variable
``ASAN_OPTIONS=check_initialization_order=1``.
+Blacklist
+---------
+
+AddressSanitizer supports ``src`` and ``fun`` entity types in
+:doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
+in the specified source files or functions. Additionally, AddressSanitizer
+introduces ``global`` and ``type`` entity types that can be used to
+suppress error reports for out-of-bound access to globals with certain
+names and types (you may only specify class or struct types).
+
+You may use an ``init`` category to suppress reports about initialization-order
+problems happening in certain source files or with certain global variables.
+
+.. code-block:: bash
+
+ # Suppress error reports for code in a file or in a function:
+ src:bad_file.cpp
+ # Ignore all functions with names containing MyFooBar:
+ fun:*MyFooBar*
+ # Disable out-of-bound checks for global:
+ global:bad_array
+ # Disable out-of-bound checks for global instances of a given class ...
+ type:class.Namespace::BadClassName
+ # ... or a given struct. Use wildcard to deal with anonymous namespace.
+ type:struct.Namespace2::*::BadStructName
+ # Disable initialization-order checks for globals:
+ global:bad_init_global=init
+ type:*BadInitClassSubstring*=init
+ src:bad/init/files/*=init
+
Supported Platforms
===================
Modified: cfe/trunk/docs/MemorySanitizer.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/MemorySanitizer.rst?rev=187871&r1=187870&r2=187871&view=diff
==============================================================================
--- cfe/trunk/docs/MemorySanitizer.rst (original)
+++ cfe/trunk/docs/MemorySanitizer.rst Wed Aug 7 03:23:32 2013
@@ -93,6 +93,15 @@ supported by other compilers, so we sugg
``__has_feature(memory_sanitizer)``. Note: currently, this attribute will be
lost if the function is inlined.
+Blacklist
+---------
+
+MemorySanitizer supports ``src`` and ``fun`` entity types in
+:doc:`SanitizerSpecialCaseList`, that can be used to relax MemorySanitizer
+checks for certain source files and functions. All "Use of uninitialized value"
+warnings will be suppressed and all values loaded from memory will be
+considered fully initialized.
+
Origin Tracking
===============
Added: cfe/trunk/docs/SanitizerSpecialCaseList.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/SanitizerSpecialCaseList.rst?rev=187871&view=auto
==============================================================================
--- cfe/trunk/docs/SanitizerSpecialCaseList.rst (added)
+++ cfe/trunk/docs/SanitizerSpecialCaseList.rst Wed Aug 7 03:23:32 2013
@@ -0,0 +1,79 @@
+===========================
+Sanitizer special case list
+===========================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+This document describes the way to disable or alter the behavior of
+sanitizer tools for certain source-level entities by providing a special
+file at compile-time.
+
+Goal and usage
+==============
+
+User of sanitizer tools, such as :doc:`AddressSanitizer`, :doc:`ThreadSanitizer`
+or :doc:`MemorySanitizer` may want to disable or alter some checks for
+certain source-level entities 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 create a file listing the entities he wants to
+ignore, and pass it to clang at compile-time using
+``-fsanitize-blacklist`` flag. See :doc:`UsersManual` for details.
+
+Example
+=======
+
+.. code-block:: bash
+
+ $ cat foo.c
+ #include <stdlib.h>
+ void bad_foo() {
+ int *a = (int*)malloc(40);
+ a[10] = 1;
+ }
+ int main() { bad_foo(); }
+ $ cat blacklist.txt
+ # Ignore reports from bad_foo function.
+ fun:bad_foo
+ $ clang -fsanitize=address foo.c ; ./a.out
+ # AddressSanitizer prints an error report.
+ $ clang -fsanitize=address -fsanitize-blacklist=blacklist.txt foo.c ; ./a.out
+ # No error report here.
+
+Format
+======
+
+Each line contains an entity type, followed by a colon and a regular
+expression, specifying the names of the entities, optionally followed by
+an equals sign and a tool-specific category. Empty lines and lines starting
+with "#" are ignored. The meanining of ``*`` in regular expression for entity
+names is different - it is treated as in shell wildcarding. Two generic
+entity types are ``src`` and ``fun``, which allow user to add, respectively,
+source files and functions to special case list. Some sanitizer tools may
+introduce custom entity types - refer to tool-specific docs.
+
+.. code-block:: bash
+
+ # 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
+ # Extended regular expressions are supported:
+ fun:bad_(foo|bar)
+ src:bad_source[1-9].c
+ # Shell like usage of * is supported (* is treated as .*):
+ src:bad/sources/*
+ fun:*BadFunction*
+ # Specific sanitizer tools may introduce categories.
+ src:/special/path/*=special_sources
Modified: cfe/trunk/docs/ThreadSanitizer.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ThreadSanitizer.rst?rev=187871&r1=187870&r2=187871&view=diff
==============================================================================
--- cfe/trunk/docs/ThreadSanitizer.rst (original)
+++ cfe/trunk/docs/ThreadSanitizer.rst Wed Aug 7 03:23:32 2013
@@ -97,6 +97,13 @@ supported by other compilers, so we sugg
``__has_feature(thread_sanitizer)``. Note: currently, this attribute will be
lost if the function is inlined.
+Blacklist
+---------
+
+ThreadSanitizer supports ``src`` and ``fun`` entity types in
+:doc:`SanitizerSpecialCaseList`, that can be used to suppress data race reports in
+the specified source files or functions.
+
Limitations
-----------
Modified: cfe/trunk/docs/UsersManual.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=187871&r1=187870&r2=187871&view=diff
==============================================================================
--- cfe/trunk/docs/UsersManual.rst (original)
+++ cfe/trunk/docs/UsersManual.rst Wed Aug 7 03:23:32 2013
@@ -940,6 +940,15 @@ are listed below.
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``):
Modified: cfe/trunk/docs/index.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/index.rst?rev=187871&r1=187870&r2=187871&view=diff
==============================================================================
--- cfe/trunk/docs/index.rst (original)
+++ cfe/trunk/docs/index.rst Wed Aug 7 03:23:32 2013
@@ -21,6 +21,7 @@ Using Clang as a Compiler
AddressSanitizer
ThreadSanitizer
MemorySanitizer
+ SanitizerSpecialCaseList
Modules
FAQ
More information about the cfe-commits
mailing list