Module std::ptrStable

Operations on unsafe pointers, *const T, and *mut T.

Working with unsafe pointers in Rust is uncommon, typically limited to a few patterns.

Use the null function to create null pointers, the is_null methods of the PtrExt trait to check for null. The PtrExt trait is imported by the prelude, so is_null etc. work everywhere. The PtrExt also defines the offset method, for pointer math.

Common ways to create unsafe pointers

1. Coerce a reference (&T) or mutable reference (&mut T).

fn main() { let my_num: i32 = 10; let my_num_ptr: *const i32 = &my_num; let mut my_speed: i32 = 88; let my_speed_ptr: *mut i32 = &mut my_speed; }

let my_num: i32 = 10;
let my_num_ptr: *const i32 = &my_num;
let mut my_speed: i32 = 88;
let my_speed_ptr: *mut i32 = &mut my_speed;

This does not take ownership of the original allocation and requires no resource management later, but you must not use the pointer after its lifetime.

2. Transmute an owned box (Box<T>).

The transmute function takes, by value, whatever it's given and returns it as whatever type is requested, as long as the types are the same size. Because Box<T> and *mut T have the same representation they can be trivially, though unsafely, transformed from one type to the other.

fn main() { use std::mem; unsafe { let my_num: Box<i32> = Box::new(10); let my_num: *const i32 = mem::transmute(my_num); let my_speed: Box<i32> = Box::new(88); let my_speed: *mut i32 = mem::transmute(my_speed); // By taking ownership of the original `Box<T>` though // we are obligated to transmute it back later to be destroyed. drop(mem::transmute::<_, Box<i32>>(my_speed)); drop(mem::transmute::<_, Box<i32>>(my_num)); } }

use std::mem;

unsafe {
    let my_num: Box<i32> = Box::new(10);
    let my_num: *const i32 = mem::transmute(my_num);
    let my_speed: Box<i32> = Box::new(88);
    let my_speed: *mut i32 = mem::transmute(my_speed);

    // By taking ownership of the original `Box<T>` though
    // we are obligated to transmute it back later to be destroyed.
    drop(mem::transmute::<_, Box<i32>>(my_speed));
    drop(mem::transmute::<_, Box<i32>>(my_num));
}

Note that here the call to drop is for clarity - it indicates that we are done with the given value and it should be destroyed.

3. Get it from C.

extern crate libc; use std::mem; fn main() { unsafe { let my_num: *mut i32 = libc::malloc(mem::size_of::<i32>() as libc::size_t) as *mut i32; if my_num.is_null() { panic!("failed to allocate memory"); } libc::free(my_num as *mut libc::c_void); } }

extern crate libc;

use std::mem;

fn main() {
    unsafe {
        let my_num: *mut i32 = libc::malloc(mem::size_of::<i32>() as libc::size_t) as *mut i32;
        if my_num.is_null() {
            panic!("failed to allocate memory");
        }
        libc::free(my_num as *mut libc::c_void);
    }
}

Usually you wouldn't literally use malloc and free from Rust, but C APIs hand out a lot of pointers generally, so are a common source of unsafe pointers in Rust.

Structs

Unique

A wrapper around a raw *mut T that indicates that the possessor of this wrapper owns the referent. This in turn implies that the Unique<T> is Send/Sync if T is Send/Sync, unlike a raw *mut T (which conveys no particular ownership semantics). It also implies that the referent of the pointer should not be modified without a unique path to the Unique reference. Useful for building abstractions like Vec<T> or Box<T>, which internally use raw pointers to manage the memory that they own.

Traits

MutPtrExt	Methods on mutable raw pointers
PtrExt	Methods on raw pointers

Functions

copy_memory	Copies count * size_of<T> bytes from src to dst. The source and destination may overlap.
copy_nonoverlapping_memory	Copies count * size_of<T> bytes from src to dst. The source and destination may not overlap.
null	Creates a null raw pointer.
null_mut	Creates a null mutable raw pointer.
read	Reads the value from src without moving it. This leaves the memory in src unchanged.
read_and_zero	Reads the value from src and nulls it out without dropping it.
replace	Replaces the value at dest with src, returning the old value, without dropping either.
set_memory	Invokes memset on the specified pointer, setting count * size_of::<T>() bytes of memory starting at dst to c.
swap	Swaps the values at two mutable locations of the same type, without deinitialising either. They may overlap, unlike mem::swap which is otherwise equivalent.
write	Overwrites a memory location with the given value without reading or dropping the old value.
zero_memory	Zeroes out count * size_of::<T> bytes of memory at dst. count may be 0.