src/doc/unstable-book/src/compiler-flags/sanitizer.md

   1 # `sanitizer`
   2
   3 The tracking issue for this feature is: [#39699](https://github.com/rust-lang/rust/issues/39699).
   4
   5 ------------------------
   6
   7 This feature allows for use of one of following sanitizers:
   8
   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.
  15
  16 To enable a sanitizer compile with `-Zsanitizer=address`,
  17 `-Zsanitizer=hwaddress`, `-Zsanitizer=leak`, `-Zsanitizer=memory` or
  18 `-Zsanitizer=thread`.
  19
  20 # AddressSanitizer
  21
  22 AddressSanitizer is a memory error detector. It can detect the following types
  23 of bugs:
  24
  25 * Out of bound accesses to heap, stack and globals
  26 * Use after free
  27 * Use after return (runtime flag `ASAN_OPTIONS=detect_stack_use_after_return=1`)
  28 * Use after scope
  29 * Double-free, invalid free
  30 * Memory leaks
  31
  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.
  34
  35 AddressSanitizer is supported on the following targets:
  36
  37 * `aarch64-apple-darwin`
  38 * `aarch64-fuchsia`
  39 * `aarch64-unknown-linux-gnu`
  40 * `x86_64-apple-darwin`
  41 * `x86_64-fuchsia`
  42 * `x86_64-unknown-freebsd`
  43 * `x86_64-unknown-linux-gnu`
  44
  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
  47 reports.
  48
  49 ## Examples
  50
  51 Stack buffer overflow:
  52
  53 ```rust
  54 fn main() {
  55     let xs = [0, 1, 2, 3];
  56     let _y = unsafe { *xs.as_ptr().offset(4) };
  57 }
  58 ```
  59
  60 ```shell
  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
  66     ...
  67
  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
  70
  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):
  89   Addressable:           00
  90   Partially addressable: 01 02 03 04 05 06 07
  91   Heap left redzone:       fa
  92   Freed heap region:       fd
  93   Stack left redzone:      f1
  94   Stack mid redzone:       f2
  95   Stack right redzone:     f3
  96   Stack after return:      f5
  97   Stack use after scope:   f8
  98   Global redzone:          f9
  99   Global init order:       f6
 100   Poisoned by user:        f7
 101   Container overflow:      fc
 102   Array cookie:            ac
 103   Intra object redzone:    bb
 104   ASan internal:           fe
 105   Left alloca redzone:     ca
 106   Right alloca redzone:    cb
 107   Shadow gap:              cc
 108 ==37882==ABORTING
 109 ```
 110
 111 Use of a stack object after its scope has already ended:
 112
 113 ```rust
 114 static mut P: *mut usize = std::ptr::null_mut();
 115
 116 fn main() {
 117     unsafe {
 118         {
 119             let mut x = 0;
 120             P = &mut x;
 121         }
 122         std::ptr::write_volatile(P, 123);
 123     }
 124 }
 125 ```
 126
 127 ```shell
 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
 135     ...
 136
 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
 139
 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):
 158   Addressable:           00
 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
 167   Global redzone:          f9
 168   Global init order:       f6
 169   Poisoned by user:        f7
 170   Container overflow:      fc
 171   Array cookie:            ac
 172   Intra object redzone:    bb
 173   ASan internal:           fe
 174   Left alloca redzone:     ca
 175   Right alloca redzone:    cb
 176   Shadow gap:              cc
 177 ==39249==ABORTING
 178 ```
 179
 180 # HWAddressSanitizer
 181
 182 HWAddressSanitizer is a newer variant of AddressSanitizer that consumes much
 183 less memory.
 184
 185 HWAddressSanitizer is supported on the following targets:
 186
 187 * `aarch64-linux-android`
 188 * `aarch64-unknown-linux-gnu`
 189
 190 HWAddressSanitizer requires `tagged-globals` target feature to instrument
 191 globals. To enable this target feature compile with `-C
 192 target-feature=+tagged-globals`
 193
 194 ## Example
 195
 196 Heap buffer overflow:
 197
 198 ```rust
 199 fn main() {
 200     let xs = vec![0, 1, 2, 3];
 201     let _y = unsafe { *xs.as_ptr().offset(4) };
 202 }
 203 ```
 204
 205 ```shell
 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
 209 ```
 210
 211 ```shell
 212 $ ./main
 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)
 216     ...
 217
 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)
 220 allocated here:
 221     #0 0xaaaae0acb80c  (/.../main+0x3b80c)
 222     ...
 223
 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)
 258 ```
 259
 260 # LeakSanitizer
 261
 262 LeakSanitizer is run-time memory leak detector.
 263
 264 LeakSanitizer is supported on the following targets:
 265
 266 * `aarch64-apple-darwin`
 267 * `aarch64-unknown-linux-gnu`
 268 * `x86_64-apple-darwin`
 269 * `x86_64-unknown-linux-gnu`
 270
 271 # MemorySanitizer
 272
 273 MemorySanitizer is detector of uninitialized reads.
 274
 275 MemorySanitizer is supported on the following targets:
 276
 277 * `aarch64-unknown-linux-gnu`
 278 * `x86_64-unknown-freebsd`
 279 * `x86_64-unknown-linux-gnu`
 280
 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.
 284
 285 ## Example
 286
 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:
 291
 292 ```rust
 293 use std::mem::MaybeUninit;
 294
 295 fn main() {
 296     unsafe {
 297         let a = MaybeUninit::<[usize; 4]>::uninit();
 298         let a = a.assume_init();
 299         println!("{}", a[2]);
 300     }
 301 }
 302 ```
 303
 304 ```shell
 305 $ export \
 306   RUSTFLAGS='-Zsanitizer=memory -Zsanitizer-memory-track-origins' \
 307   RUSTDOCFLAGS='-Zsanitizer=memory -Zsanitizer-memory-track-origins'
 308 $ cargo clean
 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
 312 ...
 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
 316
 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
 319 ```
 320
 321 # ThreadSanitizer
 322
 323 ThreadSanitizer is a data race detection tool. It is supported on the following
 324 targets:
 325
 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`
 331
 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.
 338
 339 ThreadSanitizer does not support atomic fences `std::sync::atomic::fence`,
 340 nor synchronization performed using inline assembly code.
 341
 342 ## Example
 343
 344 ```rust
 345 static mut A: usize = 0;
 346
 347 fn main() {
 348     let t = std::thread::spawn(|| {
 349         unsafe { A += 1 };
 350     });
 351     unsafe { A += 1 };
 352
 353     t.join().unwrap();
 354 }
 355 ```
 356
 357 ```shell
 358 $ export RUSTFLAGS=-Zsanitizer=thread RUSTDOCFLAGS=-Zsanitizer=thread
 359 $ cargo run -Zbuild-std --target x86_64-unknown-linux-gnu
 360 ==================
 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)
 364     ...
 365
 366   Previous write of size 8 at 0x5632dfe3d030 by main thread:
 367     #0 example::main::h628ffc6626ed85b2 /.../src/main.rs:7:14 (example+0x868c8)
 368     ...
 369     #11 main <null> (example+0x86a1a)
 370
 371   Location is global 'example::A::h43ac149ddf992709' of size 8 at 0x5632dfe3d030 (example+0x000000bd9030)
 372 ```
 373
 374 # Instrumentation of external dependencies and std
 375
 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
 380 false positives).
 381
 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].
 385
 386 [build-std]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std
 387
 388 # Build scripts and procedural macros
 389
 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
 393 version of rustc.
 394
 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
 397 macros.
 398
 399 # Symbolizing the Reports
 400
 401 Sanitizers produce symbolized stacktraces when llvm-symbolizer binary is in `PATH`.
 402
 403 # Additional Information
 404
 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]
 411
 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