Home | History | Annotate | Download | only in docs 
      1 ==============
      2 SanitizerStats
      3 ==============
      4 
      5 .. contents::
      6    :local:
      7 
      8 Introduction
      9 ============
     10 
     11 The sanitizers support a simple mechanism for gathering profiling statistics
     12 to help understand the overhead associated with sanitizers.
     13 
     14 How to build and run
     15 ====================
     16 
     17 SanitizerStats can currently only be used with :doc:`ControlFlowIntegrity`.
     18 In addition to ``-fsanitize=cfi*``, pass the ``-fsanitize-stats`` flag.
     19 This will cause the program to count the number of times that each control
     20 flow integrity check in the program fires.
     21 
     22 At run time, set the ``SANITIZER_STATS_PATH`` environment variable to direct
     23 statistics output to a file. The file will be written on process exit.
     24 The following substitutions will be applied to the environment variable:
     25 
     26   - ``%b`` -- The executable basename.
     27   - ``%p`` -- The process ID.
     28 
     29 You can also send the ``SIGUSR2`` signal to a process to make it write
     30 sanitizer statistics immediately.
     31 
     32 The ``sanstats`` program can be used to dump statistics. It takes as a
     33 command line argument the path to a statistics file produced by a program
     34 compiled with ``-fsanitize-stats``.
     35 
     36 The output of ``sanstats`` is in four columns, separated by spaces. The first
     37 column is the file and line number of the call site. The second column is
     38 the function name. The third column is the type of statistic gathered (in
     39 this case, the type of control flow integrity check). The fourth column is
     40 the call count.
     41 
     42 Example:
     43 
     44 .. code-block:: console
     45 
     46     $ cat -n vcall.cc
     47          1 struct A {
     48          2   virtual void f() {}
     49          3 };
     50          4
     51          5 __attribute__((noinline)) void g(A *a) {
     52          6   a->f();
     53          7 }
     54          8
     55          9 int main() {
     56         10   A a;
     57         11   g(&a);
     58         12 }
     59     $ clang++ -fsanitize=cfi -flto -fuse-ld=gold vcall.cc -fsanitize-stats -g
     60     $ SANITIZER_STATS_PATH=a.stats ./a.out
     61     $ sanstats a.stats
     62     vcall.cc:6 _Z1gP1A cfi-vcall 1
     63