Alexey Samsonov | 05654ff | 2013-08-07 08:23:32 +0000 | [diff] [blame] | 1 | =========================== |
| 2 | Sanitizer special case list |
| 3 | =========================== |
| 4 | |
| 5 | .. contents:: |
| 6 | :local: |
| 7 | |
| 8 | Introduction |
| 9 | ============ |
| 10 | |
| 11 | This document describes the way to disable or alter the behavior of |
| 12 | sanitizer tools for certain source-level entities by providing a special |
| 13 | file at compile-time. |
| 14 | |
| 15 | Goal and usage |
| 16 | ============== |
| 17 | |
| 18 | User of sanitizer tools, such as :doc:`AddressSanitizer`, :doc:`ThreadSanitizer` |
| 19 | or :doc:`MemorySanitizer` may want to disable or alter some checks for |
| 20 | certain source-level entities to: |
| 21 | |
| 22 | * speedup hot function, which is known to be correct; |
| 23 | * ignore a function that does some low-level magic (e.g. walks through the |
| 24 | thread stack, bypassing the frame boundaries); |
| 25 | * ignore a known problem. |
| 26 | |
| 27 | To achieve this, user may create a file listing the entities he wants to |
| 28 | ignore, and pass it to clang at compile-time using |
| 29 | ``-fsanitize-blacklist`` flag. See :doc:`UsersManual` for details. |
| 30 | |
| 31 | Example |
| 32 | ======= |
| 33 | |
| 34 | .. code-block:: bash |
| 35 | |
| 36 | $ cat foo.c |
| 37 | #include <stdlib.h> |
| 38 | void bad_foo() { |
| 39 | int *a = (int*)malloc(40); |
| 40 | a[10] = 1; |
| 41 | } |
| 42 | int main() { bad_foo(); } |
| 43 | $ cat blacklist.txt |
| 44 | # Ignore reports from bad_foo function. |
| 45 | fun:bad_foo |
| 46 | $ clang -fsanitize=address foo.c ; ./a.out |
| 47 | # AddressSanitizer prints an error report. |
| 48 | $ clang -fsanitize=address -fsanitize-blacklist=blacklist.txt foo.c ; ./a.out |
| 49 | # No error report here. |
| 50 | |
| 51 | Format |
| 52 | ====== |
| 53 | |
| 54 | Each line contains an entity type, followed by a colon and a regular |
| 55 | expression, specifying the names of the entities, optionally followed by |
| 56 | an equals sign and a tool-specific category. Empty lines and lines starting |
| 57 | with "#" are ignored. The meanining of ``*`` in regular expression for entity |
| 58 | names is different - it is treated as in shell wildcarding. Two generic |
| 59 | entity types are ``src`` and ``fun``, which allow user to add, respectively, |
| 60 | source files and functions to special case list. Some sanitizer tools may |
| 61 | introduce custom entity types - refer to tool-specific docs. |
| 62 | |
| 63 | .. code-block:: bash |
| 64 | |
| 65 | # Lines starting with # are ignored. |
| 66 | # Turn off checks for the source file (use absolute path or path relative |
| 67 | # to the current working directory): |
| 68 | src:/path/to/source/file.c |
| 69 | # Turn off checks for a particular functions (use mangled names): |
| 70 | fun:MyFooBar |
| 71 | fun:_Z8MyFooBarv |
| 72 | # Extended regular expressions are supported: |
| 73 | fun:bad_(foo|bar) |
| 74 | src:bad_source[1-9].c |
| 75 | # Shell like usage of * is supported (* is treated as .*): |
| 76 | src:bad/sources/* |
| 77 | fun:*BadFunction* |
| 78 | # Specific sanitizer tools may introduce categories. |
| 79 | src:/special/path/*=special_sources |