|
150
|
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 they want to
|
|
|
28 ignore, and pass it to clang at compile-time using
|
|
221
|
29 ``-fsanitize-ignorelist`` flag. See :doc:`UsersManual` for details.
|
|
150
|
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(); }
|
|
221
|
43 $ cat ignorelist.txt
|
|
150
|
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.
|
|
221
|
48 $ clang -fsanitize=address -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out
|
|
150
|
49 # No error report here.
|
|
|
50
|
|
|
51 Format
|
|
|
52 ======
|
|
|
53
|
|
221
|
54 Ignorelists consist of entries, optionally grouped into sections. Empty lines
|
|
|
55 and lines starting with "#" are ignored.
|
|
150
|
56
|
|
|
57 Section names are regular expressions written in square brackets that denote
|
|
|
58 which sanitizer the following entries apply to. For example, ``[address]``
|
|
|
59 specifies AddressSanitizer while ``[cfi-vcall|cfi-icall]`` specifies Control
|
|
|
60 Flow Integrity virtual and indirect call checking. Entries without a section
|
|
|
61 will be placed under the ``[*]`` section applying to all enabled sanitizers.
|
|
|
62
|
|
|
63 Entries contain an entity type, followed by a colon and a regular expression,
|
|
|
64 specifying the names of the entities, optionally followed by an equals sign and
|
|
|
65 a tool-specific category, e.g. ``fun:*ExampleFunc=example_category``. The
|
|
|
66 meaning of ``*`` in regular expression for entity names is different - it is
|
|
|
67 treated as in shell wildcarding. Two generic entity types are ``src`` and
|
|
|
68 ``fun``, which allow users to specify source files and functions, respectively.
|
|
|
69 Some sanitizer tools may introduce custom entity types and categories - refer to
|
|
|
70 tool-specific docs.
|
|
|
71
|
|
|
72 .. code-block:: bash
|
|
|
73
|
|
|
74 # Lines starting with # are ignored.
|
|
|
75 # Turn off checks for the source file (use absolute path or path relative
|
|
|
76 # to the current working directory):
|
|
|
77 src:/path/to/source/file.c
|
|
|
78 # Turn off checks for a particular functions (use mangled names):
|
|
|
79 fun:MyFooBar
|
|
|
80 fun:_Z8MyFooBarv
|
|
|
81 # Extended regular expressions are supported:
|
|
|
82 fun:bad_(foo|bar)
|
|
|
83 src:bad_source[1-9].c
|
|
|
84 # Shell like usage of * is supported (* is treated as .*):
|
|
|
85 src:bad/sources/*
|
|
|
86 fun:*BadFunction*
|
|
|
87 # Specific sanitizer tools may introduce categories.
|
|
|
88 src:/special/path/*=special_sources
|
|
221
|
89 # Sections can be used to limit ignorelist entries to specific sanitizers
|
|
150
|
90 [address]
|
|
|
91 fun:*BadASanFunc*
|
|
|
92 # Section names are regular expressions
|
|
|
93 [cfi-vcall|cfi-icall]
|
|
|
94 fun:*BadCfiCall
|
|
|
95 # Entries without sections are placed into [*] and apply to all sanitizers
|
