|
| 1 | +# Sanitizers |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +Sanitizers are a set of compiler-based runtime error detection tools that |
| 6 | +instrument programs to detect bugs during execution. They work by instrumenting |
| 7 | +code at compile time and runtime to monitor program behavior and detect specific |
| 8 | +classes of errors at runtime. Sanitizers enable precise, low-overhead runtime |
| 9 | +bug detection, improving software reliability and security. |
| 10 | + |
| 11 | +This option allows for use of one or more of these sanitizers: |
| 12 | + |
| 13 | + * [AddressSanitizer (ASan)](#addresssanitizer): Detects memory errors (e.g., |
| 14 | + buffer overflows, use after free). |
| 15 | + * [LeakSanitizer (LSan)](#leaksanitizer): Detects memory leaks either as part |
| 16 | + of AddressSanitizer or as a standalone tool. |
| 17 | + |
| 18 | +These are the valid values for this option for targets that support one or more |
| 19 | +of these sanitizers: |
| 20 | + |
| 21 | +| Target | Sanitizers | |
| 22 | +|-----------------------------|-----------------| |
| 23 | +| aarch64-unknown-linux-gnu | address, leak | |
| 24 | +| i686-pc-windows-msvc | address | |
| 25 | +| i686-unknown-linux-gnu | address | |
| 26 | +| x86_64-apple-darwin | address, leak | |
| 27 | +| x86_64-pc-windows-msvc | address | |
| 28 | +| x86_64-unknown-linux-gnu | address, leak | |
| 29 | + |
| 30 | +## AddressSanitizer |
| 31 | + |
| 32 | +AddressSanitizer (ASan) detects memory errors by instrumenting code at compile |
| 33 | +time and runtime to mark regions around allocated memory (i.e., red zones) as |
| 34 | +unaddressable (i.e., poisoned), quarantine and mark deallocated memory as |
| 35 | +unaddressable, and add checks before memory accesses. It uses a shadow memory |
| 36 | +mapping to store metadata information about whether a memory region is |
| 37 | +addressable. It can detect: |
| 38 | + |
| 39 | +* Heap-based buffer overflows, Stack-based buffer overflows, and other variants |
| 40 | + of out-of-bounds reads and writes. |
| 41 | +* Use after free, double free, and other variants of expired pointer dereference |
| 42 | + (also known as “dangling pointer”). |
| 43 | +* Initialization order bugs (such as [“Static Initialization Order |
| 44 | + Fiasco”](https://en.cppreference.com/w/cpp/language/siof)). |
| 45 | +* Memory leaks. |
| 46 | + |
| 47 | +AddressSanitizer uses both instrumentation at compile time and runtime. It is |
| 48 | +recommended to recompile all code using AddressSanitizer for best results. If |
| 49 | +parts of the compiled code are not instrumented, AddressSanitizer may not detect |
| 50 | +certain memory errors or detect false positives. |
| 51 | + |
| 52 | +AddressSanitizer increases memory usage and also impacts performance due to the |
| 53 | +red zones and shadow memory mapping, and the added checks before memory |
| 54 | +accesses. AddressSanitizer and its runtime are not suitable for production use. |
| 55 | + |
| 56 | +For more information, see the [AddressSanitizer |
| 57 | +documentation](https://clang.llvm.org/docs/AddressSanitizer.html). |
| 58 | + |
| 59 | +## LeakSanitizer |
| 60 | + |
| 61 | +LeakSanitizer (LSan) detects memory leaks either as part of AddressSanitizer or |
| 62 | +as a standalone tool by instrumenting code at runtime to track all memory and |
| 63 | +thread management functions (i.e., interceptors), and searching for memory that |
| 64 | +remain allocated but are no longer reachable by any references in the program, |
| 65 | +at program termination or during specific checkpoints. |
| 66 | + |
| 67 | +LeakSanitizer can detect: |
| 68 | + |
| 69 | +* Memory allocated dynamically (e.g., via `malloc`, `new`) that are not freed or |
| 70 | + deleted and is no longer referenced in the program (i.e., directly leaked |
| 71 | + memory). |
| 72 | +* Memory allocated dynamically that is referenced by another memory that are not |
| 73 | + freed or deleted and is no longer referenced in the program (i.e., indirectly |
| 74 | + leaked memory). |
| 75 | + |
| 76 | +LeakSanitizer does not use instrumentation at compile time and works without |
| 77 | +recompiling all code using LeakSanitizer. |
| 78 | + |
| 79 | +LeakSanitizer impacts performance due to the interceptors and the checks for |
| 80 | +memory leaks at program termination. LeakSanitizer and its runtime are not |
| 81 | +suitable for production use. |
| 82 | + |
| 83 | +For more information, see the [LeakSanitizer |
| 84 | +documentation](https://clang.llvm.org/docs/LeakSanitizer.html). |
| 85 | + |
| 86 | +## Disclaimer |
| 87 | + |
| 88 | +The quality of the Sanitizers implementation and support varies across operating |
| 89 | +systems and architectures, and relies heavily on LLVM implementation--they are |
| 90 | +mostly implemented in and supported by LLVM. |
| 91 | + |
| 92 | +Using a different LLVM or runtime version than the one used by the Rust compiler |
| 93 | +is not supported. Using Sanitizers in mixed-language binaries (also known as |
| 94 | +“mixed binaries”) is supported when the same LLVM and runtime version is used by |
| 95 | +all languages. |
0 commit comments