layout: default title: What does Rust's “unsafe” mean? description: > Exploring Rust's escape hatch for writing low-level code that the powerful type system of Rust cannot guarantee to be safe. comments: r_rust: "http://www.reddit.com/r/rust/comments/2bhwgc/what_does_rusts_unsafe_mean/" r_programming: "http://www.reddit.com/r/programming/comments/2bhwhl/what_does_rusts_unsafe_mean/" # hn: "https://news.ycombinator.com/item?id=8288572"

Rust is an in-development¹ systems programming language with a strong focus on no-overhead memory safety. This is achieved through a powerful type system (with similarities to Haskell), and careful tracking of ownership and pointers, guaranteeing safety. However, this is too restrictive for a low-level systems language, an escape hatch is occasionally required. Enter the unsafe keyword.

The Vec<T> type is defined as:

{% highlight rust linenos %} pub struct Vec { len: uint, cap: uint, ptr: *mut T } {% endhighlight %}

There are (at least) two invariants here:

1. ptr holds an allocation with enough space for cap values of type T
2. That allocation holds len valid values of type T (i.e. the first len out of cap of the Ts are valid, implying len <= cap)

It's not feasible to express these in Rust's type system, so they are guaranteed by a careful implementation. The implementation is then forced to use unsafe to assuage the compiler's doubts about certain operations. The compiler does not and cannot understand the invariants stated above, and so cannot be sure that creating a slice view into the vector is safe. It is implemented like so:

{% highlight rust linenos %} fn as_slice<'a>(&'a self) -> &'a [T] { unsafe { mem::transmute(Slice { data: self.as_ptr(), len: self.len }) } } {% endhighlight %}

And you can see that it could easily be unsafe e.g. if one accidentally wrote self.cap instead of self.len, the resulting slice would be too long and the last elements of it would be uninitialised data. The compiler can't verify that this is correct, and so assumes the worst, disallowing it without the explicit opt-in.

Another thing to note is these Vec invariants are required to always hold or else Vec will be allowing incorrect behaviour to happen via the safe methods it exposes (e.g. if someone could increase len without initialising the elements appropriately, the as_slice method above would be broken).

Unfortunately, it's not possible to get the Rust compiler to directly enforce them, so the Vec API has to be careful to guarantee that they can't be violated; part of this is keeping the fields private, so they cannot be directly changed, another part is being careful to mark the unsafe parts of the API as unsafe, e.g. the set_len method can directly change the len field.

The C function malloc is described by my man page as the following:

The malloc() function allocates size bytes and returns a pointer to the allocated memory. The memory is not initialized. If size is 0, then malloc() returns either NULL, or a unique pointer value that can later be successfully passed to free().

The malloc() and calloc() functions return a pointer to the allocated memory, which is suitably aligned for any built-in type. On error, these functions return NULL. [...].

The libc crate predefines most of the common symbols from the libc on various platforms, including libc::malloc. Let's write a safe program that creates memory for, stores and prints an 8-byte i64 integer, carefully justifying why we know more than the compiler, and thus why each unsafe is safe (in a perfect world all unsafe blocks would be justified/proved correct).

extern crate libc;
use std::ptr;

fn main() {
    let pointer: *mut i64 = unsafe {
        // rustc doesn't know what `malloc` does, and so doesn't know
        // that calling it with argument 8 is always safe; but we do,
        // so we override the compiler's concern with
        // `unsafe`. (`malloc` returns a `*mut libc::c_void` so we
        // need to cast it to the type we want.)
        libc::malloc(8) as *mut i64
    };

    // we know that the only failure condition is the pointer being
    // NULL, in any other circumstance the pointer points to a valid
    // memory allocation of at least 8 bytes.
    if pointer.is_null() {
        println!("could not allocate");
    } else {
        // here, the only thing missing is initialisation, the memory
        // is valid but uninitialised, so lets fix that. Since it is
        // not initialised, we have to be careful to avoid running
        // destructors on the old memory; via `std::ptr::write`.
        unsafe {
            // allocation is valid, and the memory is uninitialised,
            // so this is safe and correct.
            ptr::write(pointer, 1234i64);
        }

        // now `pointer` is looking at initialised, valid memory, so
        // it is valid to read from it, and to obtain a reference to
        // it.
        let data: &i64 = unsafe { &*pointer };
        println!("The data is {}", *data);
        // prints: The data is 1234
    }

    // (leaking memory is not `unsafe`.)
}

(Keen eyes will note that i64 doesn't have a destructor and so the ptr::write call isn't strictly required, but it's good practice.)

One might expect a function containing an unsafe block to be unsafe to call, that is, unsafety infects everything it touches, similar to how Haskell forces one to mark all impure calculations with the IO type.

However, this is not the case, unsafe is just an implementation detail; if a safe function uses unsafe internally, it just means the author has been forced to step around the type system, but still exposes a safe interface.

More pragmatically, if unsafe were viral, every Rust program ever would be entirely unsafe, since the whole standard library is written in Rust, built on top of unsafe internals.

The unsafe marker is a way to step around Rust's type system; by telling rustc that there are external conditions/invariants that guarantee correctness: the compiler steps back and locally leaves the programmer to verify that various properties hold. This allows Rust to write very low-level code like C, but still be memory safe by default, by forcing programmers to opt-in to the risky behaviour.

The "Writing Safe Unsafe and Low-Level Code" provides guidance and tips about using unsafe correctly.

{% include comments.html c=page.comments %}