| =========================== |
| 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 |
| ============== |
| |
| Users 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 they want to |
| ignore, and pass it to clang at compile-time using |
| ``-fsanitize-ignorelist`` 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 ignorelist.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-ignorelist=ignorelist.txt foo.c ; ./a.out |
| # No error report here. |
| |
| Format |
| ====== |
| |
| Ignorelists consist of entries, optionally grouped into sections. Empty lines |
| and lines starting with "#" are ignored. |
| |
| .. note:: |
| |
| Prior to Clang 18, section names and entries described below use a variant of |
| regex where ``*`` is translated to ``.*``. Clang 18 (`D154014 |
| <https://reviews.llvm.org/D154014>`) switches to glob and plans to remove |
| regex support in Clang 19. |
| |
| For Clang 18, regex is supported if ``#!special-case-list-v1`` is the first |
| line of the file. |
| |
| Many special case lists use ``.`` to indicate the literal character and do |
| not use regex metacharacters such as ``(``, ``)``. They are unaffected by the |
| regex to glob transition. For more details, see `this discourse post |
| <https://discourse.llvm.org/t/use-glob-instead-of-regex-for-specialcaselists/71666>`_. |
| |
| Section names are globs written in square brackets that denote |
| which sanitizer the following entries apply to. For example, ``[address]`` |
| specifies AddressSanitizer while ``[{cfi-vcall,cfi-icall}]`` specifies Control |
| Flow Integrity virtual and indirect call checking. Entries without a section |
| will be placed under the ``[*]`` section applying to all enabled sanitizers. |
| |
| Entries contain an entity type, followed by a colon and a glob, |
| specifying the names of the entities, optionally followed by an equals sign and |
| a tool-specific category, e.g. ``fun:*ExampleFunc=example_category``. |
| Two generic entity types are ``src`` and |
| ``fun``, which allow users to specify source files and functions, respectively. |
| Some sanitizer tools may introduce custom entity types and categories - refer to |
| tool-specific docs. |
| |
| .. code-block:: bash |
| |
| # The line above is explained in the note above |
| # Lines starting with # are ignored. |
| # Turn off checks for the source file |
| # Entries without sections are placed into [*] and apply to all sanitizers |
| src:path/to/source/file.c |
| src:*/source/file.c |
| # Turn off checks for this main file, including files included by it. |
| # Useful when the main file instead of an included file should be ignored. |
| mainfile:file.c |
| # Turn off checks for a particular functions (use mangled names): |
| fun:_Z8MyFooBarv |
| # Glob brace expansions and character ranges are supported |
| fun:bad_{foo,bar} |
| src:bad_source[1-9].c |
| # "*" matches zero or more characters |
| src:bad/sources/* |
| fun:*BadFunction* |
| # Specific sanitizer tools may introduce categories. |
| src:/special/path/*=special_sources |
| # Sections can be used to limit ignorelist entries to specific sanitizers |
| [address] |
| fun:*BadASanFunc* |
| # Section names are globs |
| [{cfi-vcall,cfi-icall}] |
| fun:*BadCfiCall |
| |
| ``mainfile`` is similar to applying ``-fno-sanitize=`` to a set of files but |
| does not need plumbing into the build system. This works well for internal |
| linkage functions but has a caveat for C++ vague linkage functions. |
| |
| C++ vague linkage functions (e.g. inline functions, template instantiations) are |
| deduplicated at link time. A function (in an included file) ignored by a |
| specific ``mainfile`` pattern may not be the prevailing copy picked by the |
| linker. Therefore, using ``mainfile`` requires caution. It may still be useful, |
| e.g. when patterns are picked in a way to ensure the prevailing one is ignored. |
| (There is action-at-a-distance risk.) |
| |
| ``mainfile`` can be useful enabling a ubsan check for a large code base when |
| finding the direct stack frame triggering the failure for every failure is |
| difficult. |