Skip to content

Commit cdad921

Browse files
rcvallercvalle
committed
sanitizers: Add documentation for stable sanitizers
1 parent 5cd80b6 commit cdad921

File tree

3 files changed

+140
-0
lines changed

3 files changed

+140
-0
lines changed

‎src/doc/rustc/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
- [Checking Conditional Configurations](check-cfg.md)
2525
- [Cargo Specifics](check-cfg/cargo-specifics.md)
2626
- [Exploit Mitigations](exploit-mitigations.md)
27+
- [Sanitizers](sanitizers.md)
2728
- [Symbol Mangling](symbol-mangling/index.md)
2829
- [v0 Symbol Format](symbol-mangling/v0.md)
2930
- [Contributing to `rustc`](contributing.md)

‎src/doc/rustc/src/codegen-options/index.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -573,6 +573,49 @@ This is primarily useful for local development, to ensure that all the `dylib` d
573573

574574
To set the rpath to a different value (which can be useful for distribution), `-Clink-arg` with a platform-specific linker argument can be used to set the rpath directly.
575575

576+
## sanitize
577+
578+
Sanitizers are a set of compiler-based runtime error detection tools that
579+
instrument programs to detect bugs during execution. They work by instrumenting
580+
code at compile time and runtime to monitor program behavior and detect specific
581+
classes of errors at runtime. Sanitizers enable precise, low-overhead runtime
582+
bug detection, improving software reliability and security.
583+
584+
This option allows for use of one or more of these sanitizers:
585+
586+
* [AddressSanitizer
587+
(ASan)](../sanitizers.md#addresssanitizer):
588+
Detects memory errors (e.g., buffer overflows, use after free).
589+
* [LeakSanitizer
590+
(LSan)](../sanitizers.md#leaksanitizer):
591+
Detects memory leaks either as part of AddressSanitizer or as a standalone
592+
tool.
593+
594+
These are the valid values for this option for targets that support one or more
595+
of these sanitizers:
596+
597+
| Target | Sanitizers |
598+
|-----------------------------|-----------------|
599+
| aarch64-apple-darwin | address |
600+
| aarch64-unknown-linux-gnu | address, leak |
601+
| i686-pc-windows-msvc | address |
602+
| i686-unknown-linux-gnu | address |
603+
| x86_64-apple-darwin | address, leak |
604+
| x86_64-pc-windows-msvc | address |
605+
| x86_64-unknown-linux-gnu | address, leak |
606+
607+
The quality of the Sanitizers implementation and support varies across operating
608+
systems and architectures, and relies heavily on LLVM implementation--they are
609+
mostly implemented in and supported by LLVM.
610+
611+
Using a different LLVM or runtime version than the one used by the Rust compiler
612+
is not supported. Using Sanitizers in mixed-language binaries (also known as
613+
“mixed binaries”) is supported when the same LLVM and runtime version is used by
614+
all languages.
615+
616+
For more information about the available sanitizers, see the [Sanitizers
617+
chapter](../sanitizers.md).
618+
576619
## save-temps
577620

578621
This flag controls whether temporary files generated during compilation are

‎src/doc/rustc/src/sanitizers.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
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-apple-darwin | address |
24+
| aarch64-unknown-linux-gnu | address, leak |
25+
| i686-pc-windows-msvc | address |
26+
| i686-unknown-linux-gnu | address |
27+
| x86_64-apple-darwin | address, leak |
28+
| x86_64-pc-windows-msvc | address |
29+
| x86_64-unknown-linux-gnu | address, leak |
30+
31+
## AddressSanitizer
32+
33+
AddressSanitizer (ASan) detects memory errors by instrumenting code at compile
34+
time and runtime to mark regions around allocated memory (i.e., red zones) as
35+
unaddressable (i.e., poisoned), quarantine and mark deallocated memory as
36+
unaddressable, and add checks before memory accesses. It uses a shadow memory
37+
mapping to store metadata information about whether a memory region is
38+
addressable. It can detect:
39+
40+
* Heap-based buffer overflows, Stack-based buffer overflows, and other variants
41+
of out-of-bounds reads and writes.
42+
* Use after free, double free, and other variants of expired pointer dereference
43+
(also known as “dangling pointer”).
44+
* Initialization order bugs (such as [“Static Initialization Order
45+
Fiasco”](https://en.cppreference.com/w/cpp/language/siof)).
46+
* Memory leaks.
47+
48+
AddressSanitizer uses both instrumentation at compile time and runtime. It is
49+
recommended to recompile all code using AddressSanitizer for best results. If
50+
parts of the compiled code are not instrumented, AddressSanitizer may not detect
51+
certain memory errors or detect false positives.
52+
53+
AddressSanitizer increases memory usage and also impacts performance due to the
54+
red zones and shadow memory mapping, and the added checks before memory
55+
accesses. AddressSanitizer and its runtime are not suitable for production use.
56+
57+
For more information, see the [AddressSanitizer
58+
documentation](https://clang.llvm.org/docs/AddressSanitizer.html).
59+
60+
## LeakSanitizer
61+
62+
LeakSanitizer (LSan) detects memory leaks either as part of AddressSanitizer or
63+
as a standalone tool by instrumenting code at runtime to track all memory and
64+
thread management functions (i.e., interceptors), and searching for memory that
65+
remain allocated but are no longer reachable by any references in the program,
66+
at program termination or during specific checkpoints.
67+
68+
LeakSanitizer can detect:
69+
70+
* Memory allocated dynamically (e.g., via `malloc`, `new`) that are not freed or
71+
deleted and is no longer referenced in the program (i.e., directly leaked
72+
memory).
73+
* Memory allocated dynamically that is referenced by another memory that are not
74+
freed or deleted and is no longer referenced in the program (i.e., indirectly
75+
leaked memory).
76+
77+
LeakSanitizer does not use instrumentation at compile time and works without
78+
recompiling all code using LeakSanitizer.
79+
80+
LeakSanitizer impacts performance due to the interceptors and the checks for
81+
memory leaks at program termination. LeakSanitizer and its runtime are not
82+
suitable for production use.
83+
84+
For more information, see the [LeakSanitizer
85+
documentation](https://clang.llvm.org/docs/LeakSanitizer.html).
86+
87+
## Disclaimer
88+
89+
The quality of the Sanitizers implementation and support varies across operating
90+
systems and architectures, and relies heavily on LLVM implementation--they are
91+
mostly implemented in and supported by LLVM.
92+
93+
Using a different LLVM or runtime version than the one used by the Rust compiler
94+
is not supported. Using Sanitizers in mixed-language binaries (also known as
95+
“mixed binaries”) is supported when the same LLVM and runtime version is used by
96+
all languages.

0 commit comments

Comments
 (0)