3 The tracking issue for this feature is: [#39699](https://github.com/rust-lang/rust/issues/39699).
5 ------------------------
7 This feature allows for use of one of following sanitizers:
9 * [AddressSanitizer][clang-asan] a fast memory error detector.
10 * [HWAddressSanitizer][clang-hwasan] a memory error detector similar to
11 AddressSanitizer, but based on partial hardware assistance.
12 * [LeakSanitizer][clang-lsan] a run-time memory leak detector.
13 * [MemorySanitizer][clang-msan] a detector of uninitialized reads.
14 * [ThreadSanitizer][clang-tsan] a fast data race detector.
16 To enable a sanitizer compile with `-Zsanitizer=address`,
17 `-Zsanitizer=hwaddress`, `-Zsanitizer=leak`, `-Zsanitizer=memory` or
22 AddressSanitizer is a memory error detector. It can detect the following types
25 * Out of bound accesses to heap, stack and globals
27 * Use after return (runtime flag `ASAN_OPTIONS=detect_stack_use_after_return=1`)
29 * Double-free, invalid free
32 The memory leak detection is enabled by default on Linux, and can be enabled
33 with runtime flag `ASAN_OPTIONS=detect_leaks=1` on macOS.
35 AddressSanitizer is supported on the following targets:
37 * `aarch64-apple-darwin`
39 * `aarch64-unknown-linux-gnu`
40 * `x86_64-apple-darwin`
42 * `x86_64-unknown-freebsd`
43 * `x86_64-unknown-linux-gnu`
45 AddressSanitizer works with non-instrumented code although it will impede its
46 ability to detect some bugs. It is not expected to produce false positive
51 Stack buffer overflow:
55 let xs = [0, 1, 2, 3];
56 let _y = unsafe { *xs.as_ptr().offset(4) };
61 $ export RUSTFLAGS=-Zsanitizer=address RUSTDOCFLAGS=-Zsanitizer=address
62 $ cargo run -Zbuild-std --target x86_64-unknown-linux-gnu
63 ==37882==ERROR: AddressSanitizer: stack-buffer-overflow on address 0x7ffe400e6250 at pc 0x5609a841fb20 bp 0x7ffe400e6210 sp 0x7ffe400e6208
64 READ of size 4 at 0x7ffe400e6250 thread T0
65 #0 0x5609a841fb1f in example::main::h628ffc6626ed85b2 /.../src/main.rs:3:23
68 Address 0x7ffe400e6250 is located in stack of thread T0 at offset 48 in frame
69 #0 0x5609a841f8af in example::main::h628ffc6626ed85b2 /.../src/main.rs:1
71 This frame has 1 object(s):
72 [32, 48) 'xs' (line 2) <== Memory access at offset 48 overflows this variable
73 HINT: this may be a false positive if your program uses some custom stack unwind mechanism, swapcontext or vfork
74 (longjmp and C++ exceptions *are* supported)
75 SUMMARY: AddressSanitizer: stack-buffer-overflow /.../src/main.rs:3:23 in example::main::h628ffc6626ed85b2
76 Shadow bytes around the buggy address:
77 0x100048014bf0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
78 0x100048014c00: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
79 0x100048014c10: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
80 0x100048014c20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
81 0x100048014c30: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
82 =>0x100048014c40: 00 00 00 00 f1 f1 f1 f1 00 00[f3]f3 00 00 00 00
83 0x100048014c50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
84 0x100048014c60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
85 0x100048014c70: f1 f1 f1 f1 00 00 f3 f3 00 00 00 00 00 00 00 00
86 0x100048014c80: 00 00 00 00 00 00 00 00 00 00 00 00 f1 f1 f1 f1
87 0x100048014c90: 00 00 f3 f3 00 00 00 00 00 00 00 00 00 00 00 00
88 Shadow byte legend (one shadow byte represents 8 application bytes):
90 Partially addressable: 01 02 03 04 05 06 07
93 Stack left redzone: f1
95 Stack right redzone: f3
96 Stack after return: f5
97 Stack use after scope: f8
101 Container overflow: fc
103 Intra object redzone: bb
105 Left alloca redzone: ca
106 Right alloca redzone: cb
111 Use of a stack object after its scope has already ended:
114 static mut P: *mut usize = std::ptr::null_mut();
122 std::ptr::write_volatile(P, 123);
128 $ export RUSTFLAGS=-Zsanitizer=address RUSTDOCFLAGS=-Zsanitizer=address
129 $ cargo run -Zbuild-std --target x86_64-unknown-linux-gnu
130 =================================================================
131 ==39249==ERROR: AddressSanitizer: stack-use-after-scope on address 0x7ffc7ed3e1a0 at pc 0x55c98b262a8e bp 0x7ffc7ed3e050 sp 0x7ffc7ed3e048
132 WRITE of size 8 at 0x7ffc7ed3e1a0 thread T0
133 #0 0x55c98b262a8d in core::ptr::write_volatile::he21f1df5a82f329a /.../src/rust/src/libcore/ptr/mod.rs:1048:5
134 #1 0x55c98b262cd2 in example::main::h628ffc6626ed85b2 /.../src/main.rs:9:9
137 Address 0x7ffc7ed3e1a0 is located in stack of thread T0 at offset 32 in frame
138 #0 0x55c98b262bdf in example::main::h628ffc6626ed85b2 /.../src/main.rs:3
140 This frame has 1 object(s):
141 [32, 40) 'x' (line 6) <== Memory access at offset 32 is inside this variable
142 HINT: this may be a false positive if your program uses some custom stack unwind mechanism, swapcontext or vfork
143 (longjmp and C++ exceptions *are* supported)
144 SUMMARY: AddressSanitizer: stack-use-after-scope /.../src/rust/src/libcore/ptr/mod.rs:1048:5 in core::ptr::write_volatile::he21f1df5a82f329a
145 Shadow bytes around the buggy address:
146 0x10000fd9fbe0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
147 0x10000fd9fbf0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
148 0x10000fd9fc00: 00 00 00 00 00 00 00 00 00 00 00 00 f1 f1 f1 f1
149 0x10000fd9fc10: f8 f8 f3 f3 00 00 00 00 00 00 00 00 00 00 00 00
150 0x10000fd9fc20: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
151 =>0x10000fd9fc30: f1 f1 f1 f1[f8]f3 f3 f3 00 00 00 00 00 00 00 00
152 0x10000fd9fc40: 00 00 00 00 00 00 00 00 00 00 00 00 f1 f1 f1 f1
153 0x10000fd9fc50: 00 00 f3 f3 00 00 00 00 00 00 00 00 00 00 00 00
154 0x10000fd9fc60: 00 00 00 00 00 00 00 00 f1 f1 f1 f1 00 00 f3 f3
155 0x10000fd9fc70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
156 0x10000fd9fc80: 00 00 00 00 f1 f1 f1 f1 00 00 f3 f3 00 00 00 00
157 Shadow byte legend (one shadow byte represents 8 application bytes):
159 Partially addressable: 01 02 03 04 05 06 07
160 Heap left redzone: fa
161 Freed heap region: fd
162 Stack left redzone: f1
163 Stack mid redzone: f2
164 Stack right redzone: f3
165 Stack after return: f5
166 Stack use after scope: f8
168 Global init order: f6
170 Container overflow: fc
172 Intra object redzone: bb
174 Left alloca redzone: ca
175 Right alloca redzone: cb
182 HWAddressSanitizer is a newer variant of AddressSanitizer that consumes much
185 HWAddressSanitizer is supported on the following targets:
187 * `aarch64-linux-android`
188 * `aarch64-unknown-linux-gnu`
190 HWAddressSanitizer requires `tagged-globals` target feature to instrument
191 globals. To enable this target feature compile with `-C
192 target-feature=+tagged-globals`
196 Heap buffer overflow:
200 let xs = vec![0, 1, 2, 3];
201 let _y = unsafe { *xs.as_ptr().offset(4) };
206 $ rustc main.rs -Zsanitizer=hwaddress -C target-feature=+tagged-globals -C
207 linker=aarch64-linux-gnu-gcc -C link-arg=-fuse-ld=lld --target
208 aarch64-unknown-linux-gnu
213 ==241==ERROR: HWAddressSanitizer: tag-mismatch on address 0xefdeffff0050 at pc 0xaaaae0ae4a98
214 READ of size 4 at 0xefdeffff0050 tags: 2c/00 (ptr/mem) in thread T0
215 #0 0xaaaae0ae4a94 (/.../main+0x54a94)
218 [0xefdeffff0040,0xefdeffff0060) is a small allocated heap chunk; size: 32 offset: 16
219 0xefdeffff0050 is located 0 bytes to the right of 16-byte region [0xefdeffff0040,0xefdeffff0050)
221 #0 0xaaaae0acb80c (/.../main+0x3b80c)
224 Thread: T0 0xeffe00002000 stack: [0xffffc28ad000,0xffffc30ad000) sz: 8388608 tls: [0xffffaa10a020,0xffffaa10a7d0)
225 Memory tags around the buggy address (one tag corresponds to 16 bytes):
226 0xfefcefffef80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
227 0xfefcefffef90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
228 0xfefcefffefa0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
229 0xfefcefffefb0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
230 0xfefcefffefc0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
231 0xfefcefffefd0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
232 0xfefcefffefe0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
233 0xfefcefffeff0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
234 =>0xfefceffff000: d7 d7 05 00 2c [00] 00 00 00 00 00 00 00 00 00 00
235 0xfefceffff010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
236 0xfefceffff020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
237 0xfefceffff030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
238 0xfefceffff040: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
239 0xfefceffff050: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
240 0xfefceffff060: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
241 0xfefceffff070: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
242 0xfefceffff080: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
243 Tags for short granules around the buggy address (one tag corresponds to 16 bytes):
244 0xfefcefffeff0: .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..
245 =>0xfefceffff000: .. .. 8c .. .. [..] .. .. .. .. .. .. .. .. .. ..
246 0xfefceffff010: .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..
247 See https://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.html#short-granules for a description of short granule tags
248 Registers where the failure occurred (pc 0xaaaae0ae4a98):
249 x0 2c00efdeffff0050 x1 0000000000000004 x2 0000000000000004 x3 0000000000000000
250 x4 0000fffefc30ac37 x5 000000000000005d x6 00000ffffc30ac37 x7 0000efff00000000
251 x8 2c00efdeffff0050 x9 0200efff00000000 x10 0000000000000000 x11 0200efff00000000
252 x12 0200effe00000310 x13 0200effe00000310 x14 0000000000000008 x15 5d00ffffc30ac360
253 x16 0000aaaae0ad062c x17 0000000000000003 x18 0000000000000001 x19 0000ffffc30ac658
254 x20 4e00ffffc30ac6e0 x21 0000aaaae0ac5e10 x22 0000000000000000 x23 0000000000000000
255 x24 0000000000000000 x25 0000000000000000 x26 0000000000000000 x27 0000000000000000
256 x28 0000000000000000 x29 0000ffffc30ac5a0 x30 0000aaaae0ae4a98
257 SUMMARY: HWAddressSanitizer: tag-mismatch (/.../main+0x54a94)
262 LeakSanitizer is run-time memory leak detector.
264 LeakSanitizer is supported on the following targets:
266 * `aarch64-apple-darwin`
267 * `aarch64-unknown-linux-gnu`
268 * `x86_64-apple-darwin`
269 * `x86_64-unknown-linux-gnu`
273 MemorySanitizer is detector of uninitialized reads.
275 MemorySanitizer is supported on the following targets:
277 * `aarch64-unknown-linux-gnu`
278 * `x86_64-unknown-freebsd`
279 * `x86_64-unknown-linux-gnu`
281 MemorySanitizer requires all program code to be instrumented. C/C++ dependencies
282 need to be recompiled using Clang with `-fsanitize=memory` option. Failing to
283 achieve that will result in false positive reports.
287 Detecting the use of uninitialized memory. The `-Zbuild-std` flag rebuilds and
288 instruments the standard library, and is strictly necessary for the correct
289 operation of the tool. The `-Zsanitizer-memory-track-origins` enables tracking
290 of the origins of uninitialized memory:
293 use std::mem::MaybeUninit;
297 let a = MaybeUninit::<[usize; 4]>::uninit();
298 let a = a.assume_init();
299 println!("{}", a[2]);
306 RUSTFLAGS='-Zsanitizer=memory -Zsanitizer-memory-track-origins' \
307 RUSTDOCFLAGS='-Zsanitizer=memory -Zsanitizer-memory-track-origins'
309 $ cargo run -Zbuild-std --target x86_64-unknown-linux-gnu
310 ==9416==WARNING: MemorySanitizer: use-of-uninitialized-value
311 #0 0x560c04f7488a in core::fmt::num::imp::fmt_u64::haa293b0b098501ca $RUST/build/x86_64-unknown-linux-gnu/stage1/lib/rustlib/src/rust/src/libcore/fmt/num.rs:202:16
313 Uninitialized value was stored to memory at
314 #0 0x560c04ae898a in __msan_memcpy.part.0 $RUST/src/llvm-project/compiler-rt/lib/msan/msan_interceptors.cc:1558:3
315 #1 0x560c04b2bf88 in memory::main::hd2333c1899d997f5 $CWD/src/main.rs:6:16
317 Uninitialized value was created by an allocation of 'a' in the stack frame of function '_ZN6memory4main17hd2333c1899d997f5E'
318 #0 0x560c04b2bc50 in memory::main::hd2333c1899d997f5 $CWD/src/main.rs:3
323 ThreadSanitizer is a data race detection tool. It is supported on the following
326 * `aarch64-apple-darwin`
327 * `aarch64-unknown-linux-gnu`
328 * `x86_64-apple-darwin`
329 * `x86_64-unknown-freebsd`
330 * `x86_64-unknown-linux-gnu`
332 To work correctly ThreadSanitizer needs to be "aware" of all synchronization
333 operations in a program. It generally achieves that through combination of
334 library interception (for example synchronization performed through
335 `pthread_mutex_lock` / `pthread_mutex_unlock`) and compile time instrumentation
336 (e.g. atomic operations). Using it without instrumenting all the program code
337 can lead to false positive reports.
339 ThreadSanitizer does not support atomic fences `std::sync::atomic::fence`,
340 nor synchronization performed using inline assembly code.
345 static mut A: usize = 0;
348 let t = std::thread::spawn(|| {
358 $ export RUSTFLAGS=-Zsanitizer=thread RUSTDOCFLAGS=-Zsanitizer=thread
359 $ cargo run -Zbuild-std --target x86_64-unknown-linux-gnu
361 WARNING: ThreadSanitizer: data race (pid=10574)
362 Read of size 8 at 0x5632dfe3d030 by thread T1:
363 #0 example::main::_$u7b$$u7b$closure$u7d$$u7d$::h23f64b0b2f8c9484 ../src/main.rs:5:18 (example+0x86cec)
366 Previous write of size 8 at 0x5632dfe3d030 by main thread:
367 #0 example::main::h628ffc6626ed85b2 /.../src/main.rs:7:14 (example+0x868c8)
369 #11 main <null> (example+0x86a1a)
371 Location is global 'example::A::h43ac149ddf992709' of size 8 at 0x5632dfe3d030 (example+0x000000bd9030)
374 # Instrumentation of external dependencies and std
376 The sanitizers to varying degrees work correctly with partially instrumented
377 code. On the one extreme is LeakSanitizer that doesn't use any compile time
378 instrumentation, on the other is MemorySanitizer that requires that all program
379 code to be instrumented (failing to achieve that will inevitably result in
382 It is strongly recommended to combine sanitizers with recompiled and
383 instrumented standard library, for example using [cargo `-Zbuild-std`
384 functionality][build-std].
386 [build-std]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std
388 # Build scripts and procedural macros
390 Use of sanitizers together with build scripts and procedural macros is
391 technically possible, but in almost all cases it would be best avoided. This
392 is especially true for procedural macros which would require an instrumented
395 In more practical terms when using cargo always remember to pass `--target`
396 flag, so that rustflags will not be applied to build scripts and procedural
399 # Symbolizing the Reports
401 Sanitizers produce symbolized stacktraces when llvm-symbolizer binary is in `PATH`.
403 # Additional Information
405 * [Sanitizers project page](https://github.com/google/sanitizers/wiki/)
406 * [AddressSanitizer in Clang][clang-asan]
407 * [HWAddressSanitizer in Clang][clang-hwasan]
408 * [LeakSanitizer in Clang][clang-lsan]
409 * [MemorySanitizer in Clang][clang-msan]
410 * [ThreadSanitizer in Clang][clang-tsan]
412 [clang-asan]: https://clang.llvm.org/docs/AddressSanitizer.html
413 [clang-hwasan]: https://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.html
414 [clang-lsan]: https://clang.llvm.org/docs/LeakSanitizer.html
415 [clang-msan]: https://clang.llvm.org/docs/MemorySanitizer.html
416 [clang-tsan]: https://clang.llvm.org/docs/ThreadSanitizer.html