Module std::ptrStable
[-] [+]
[src]
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.
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 |
Traits
MutPtrExt | Methods on mutable raw pointers |
PtrExt | Methods on raw pointers |
Functions
copy_memory | Copies |
copy_nonoverlapping_memory | Copies |
null | Creates a null raw pointer. |
null_mut | Creates a null mutable raw pointer. |
read | Reads the value from |
read_and_zero | Reads the value from |
replace | Replaces the value at |
set_memory | Invokes memset on the specified pointer, setting |
swap | Swaps the values at two mutable locations of the same type, without
deinitialising either. They may overlap, unlike |
write | Overwrites a memory location with the given value without reading or dropping the old value. |
zero_memory | Zeroes out |