src/doc/trpl/unsafe.md

   1 % Unsafe
   2
   3 Rust’s main draw is its powerful static guarantees about behavior. But safety
   4 checks are conservative by nature: there are some programs that are actually
   5 safe, but the compiler is not able to verify this is true. To write these kinds
   6 of programs, we need to tell the compiler to relax its restrictions a bit. For
   7 this, Rust has a keyword, `unsafe`. Code using `unsafe` has less restrictions
   8 than normal code does.
   9
  10 Let’s go over the syntax, and then we’ll talk semantics. `unsafe` is used in
  11 two contexts. The first one is to mark a function as unsafe:
  12
  13 ```rust
  14 unsafe fn danger_will_robinson() {
  15     // scary stuff
  16 }
  17 ```
  18
  19 All functions called from [FFI][ffi] must be marked as `unsafe`, for example.
  20 The second use of `unsafe` is an unsafe block:
  21
  22 [ffi]: ffi.html
  23
  24 ```rust
  25 unsafe {
  26     // scary stuff
  27 }
  28 ```
  29
  30 It’s important to be able to explicitly delineate code that may have bugs that
  31 cause big problems. If a Rust program segfaults, you can be sure it’s somewhere
  32 in the sections marked `unsafe`.
  33
  34 # What does ‘safe’ mean?
  35
  36 Safe, in the context of Rust, means “doesn’t do anything unsafe.” Easy!
  37
  38 Okay, let’s try again: what is not safe to do? Here’s a list:
  39
  40 * Data races
  41 * Dereferencing a null/dangling raw pointer
  42 * Reads of [undef][undef] (uninitialized) memory
  43 * Breaking the [pointer aliasing rules][aliasing] with raw pointers.
  44 * `&mut T` and `&T` follow LLVM’s scoped [noalias][noalias] model, except if
  45   the `&T` contains an `UnsafeCell<U>`. Unsafe code must not violate these
  46   aliasing guarantees.
  47 * Mutating an immutable value/reference without `UnsafeCell<U>`
  48 * Invoking undefined behavior via compiler intrinsics:
  49   * Indexing outside of the bounds of an object with `std::ptr::offset`
  50     (`offset` intrinsic), with
  51     the exception of one byte past the end which is permitted.
  52   * Using `std::ptr::copy_nonoverlapping_memory` (`memcpy32`/`memcpy64`
  53     intrinsics) on overlapping buffers
  54 * Invalid values in primitive types, even in private fields/locals:
  55   * Null/dangling references or boxes
  56   * A value other than `false` (0) or `true` (1) in a `bool`
  57   * A discriminant in an `enum` not included in its type definition
  58   * A value in a `char` which is a surrogate or above `char::MAX`
  59   * Non-UTF-8 byte sequences in a `str`
  60 * Unwinding into Rust from foreign code or unwinding from Rust into foreign
  61   code.
  62
  63 [noalias]: http://llvm.org/docs/LangRef.html#noalias
  64 [undef]: http://llvm.org/docs/LangRef.html#undefined-values
  65 [aliasing]: http://llvm.org/docs/LangRef.html#pointer-aliasing-rules
  66
  67 Whew! That’s a bunch of stuff. It’s also important to notice all kinds of
  68 behaviors that are certainly bad, but are expressly _not_ unsafe:
  69
  70 * Deadlocks
  71 * Reading data from private fields
  72 * Leaks due to reference count cycles
  73 * Exiting without calling destructors
  74 * Sending signals
  75 * Accessing/modifying the file system
  76 * Integer overflow
  77
  78 Rust cannot prevent all kinds of software problems. Buggy code can and will be
  79 written in Rust. These things aren’t great, but they don’t qualify as `unsafe`
  80 specifically.
  81
  82 # Unsafe Superpowers
  83
  84 In both unsafe functions and unsafe blocks, Rust will let you do three things
  85 that you normally can not do. Just three. Here they are:
  86
  87 1. Access or update a [static mutable variable][static].
  88 2. Dereference a raw pointer.
  89 3. Call unsafe functions. This is the most powerful ability.
  90
  91 That’s it. It’s important that `unsafe` does not, for example, ‘turn off the
  92 borrow checker’. Adding `unsafe` to some random Rust code doesn’t change its
  93 semantics, it won’t just start accepting anything.
  94
  95 But it will let you write things that _do_ break some of the rules. Let’s go
  96 over these three abilities in order.
  97
  98 ## Access or update a `static mut`
  99
 100 Rust has a feature called ‘`static mut`’ which allows for mutable global state.
 101 Doing so can cause a data race, and as such is inherently not safe. For more
 102 details, see the [static][static] section of the book.
 103
 104 [static]: const-and-static.html#static
 105
 106 ## Dereference a raw pointer
 107
 108 Raw pointers let you do arbitrary pointer arithmetic, and can cause a number of
 109 different memory safety and security issues. In some senses, the ability to
 110 dereference an arbitrary pointer is one of the most dangerous things you can
 111 do. For more on raw pointers, see [their section of the book][rawpointers].
 112
 113 [rawpointers]: raw-pointers.html
 114
 115 ## Call unsafe functions
 116
 117 This last ability works with both aspects of `unsafe`: you can only call
 118 functions marked `unsafe` from inside an unsafe block.
 119
 120 This ability is powerful and varied. Rust exposes some [compiler
 121 intrinsics][intrinsics] as unsafe functions, and some unsafe functions bypass
 122 safety checks, trading safety for speed.
 123
 124 I’ll repeat again: even though you _can_ do arbitrary things in unsafe blocks
 125 and functions doesn’t mean you should. The compiler will act as though you’re
 126 upholding its invariants, so be careful!
 127
 128 [intrinsics]: intrinsics.html