SanitizerSpecialCaseList.rst source code [clang_source_code/docs/SanitizerSpecialCaseList.rst]

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
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	Blacklists consist of entries, optionally grouped into sections. Empty lines and
55	lines starting with "#" are ignored.
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
89	# Sections can be used to limit blacklist entries to specific sanitizers
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
96

Clang Project