===========================
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.
Codebase Browser
llvm