Module core::ptr [] [src]

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

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

Use the null`nullfunction to create null pointers, and the` function to create null pointers, and the is_null`is_nullmethod of the` method of the *const T`*const Ttype to check for null. The` type to check for null. The *const T`*const Ttype also defines the` type also defines the offset`offset` method, for pointer math.

Common ways to create unsafe pointers

1. Coerce a reference (&T`&T) or mutable reference (`) or mutable reference (&mut T`&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>`Box`).

The into_raw`into_rawfunction consumes a box and returns the raw pointer. It doesn't destroy` function consumes a box and returns the raw pointer. It doesn't destroy T`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`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`mallocand` and free`free` from Rust, but C APIs hand out a lot of pointers generally, so are a common source of unsafe pointers in Rust.

Reexports

pub use intrinsics::copy_nonoverlapping;
pub use intrinsics::copy;
pub use intrinsics::write_bytes;

Structs

Unique [Unstable]

A wrapper around a raw *mut T`*mut Tthat indicates that the possessor of this wrapper owns the referent. This in turn implies that the` that indicates that the possessor of this wrapper owns the referent. This in turn implies that the Unique<T>`Uniqueis` is Send`Send/`/Sync`Syncif` if T`Tis` is Send`Send/`/Sync`Sync, unlike a raw`, unlike a raw *mut T`*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` (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`Uniquereference. Useful for building abstractions like` reference. Useful for building abstractions like Vec<T>`Vecor` or Box<T>`Box`, which internally use raw pointers to manage the memory that they own.

Functions

null

Creates a null raw pointer.

null_mut

Creates a null mutable raw pointer.

read

Reads the value from src`srcwithout moving it. This leaves the memory in` without moving it. This leaves the memory in src`src` unchanged.

replace

Replaces the value at dest`destwith` with src`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`mem::swap` which is otherwise equivalent.

write

Overwrites a memory location with the given value without reading or dropping the old value.

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`src` and nulls it out without dropping it.