Module std::ptr

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, and the is_null method of the *const T type to check for null. The *const T type 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;

To get a pointer to a boxed value, dereference the box:

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

let my_num: Box<i32> = Box::new(10);
let my_num_ptr: *const i32 = &*my_num;
let mut my_speed: Box<i32> = Box::new(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. Consume a box (Box<T>).

The into_raw function consumes a box and returns the raw pointer. It doesn't destroy T or deallocate any memory.

#![feature(alloc)] fn main() { use std::boxed; unsafe { let my_speed: Box<i32> = Box::new(88); let my_speed: *mut i32 = boxed::into_raw(my_speed); // By taking ownership of the original `Box<T>` though // we are obligated to put it together later to be destroyed. drop(Box::from_raw(my_speed)); } }

use std::boxed;

unsafe {
    let my_speed: Box<i32> = Box::new(88);
    let my_speed: *mut i32 = boxed::into_raw(my_speed);

    // By taking ownership of the original `Box<T>` though
    // we are obligated to put it together later to be destroyed.
    drop(Box::from_raw(my_speed));
}

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.

#![feature(libc)] 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

[Unstable] 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.

Functions

copy	Copies count * size_of<T> bytes from src to dst. The source and destination may overlap.
copy_nonoverlapping	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.
replace	Replaces the value at dest with src, returning the old value, without dropping either.
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.
write_bytes	Invokes memset on the specified pointer, setting count * size_of::<T>() bytes of memory starting at dst to c.
read_and_drop	[Unstable] Variant of read_and_zero that writes the specific drop-flag byte (which may be more appropriate than zero).
read_and_zero	[Unstable] Reads the value from src and nulls it out without dropping it.