src/libcore/ptr.rs

   1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 // FIXME: talk about offset, copy_memory, copy_nonoverlapping_memory
  12
  13 //! Operations on raw pointers, `*const T`, and `*mut T`.
  14 //!
  15 //! Working with raw pointers in Rust is uncommon,
  16 //! typically limited to a few patterns.
  17 //!
  18 //! Use the `null` function to create null pointers, and the `is_null` method
  19 //! of the `*const T` type  to check for null. The `*const T` type also defines
  20 //! the `offset` method, for pointer math.
  21 //!
  22 //! # Common ways to create raw pointers
  23 //!
  24 //! ## 1. Coerce a reference (`&T`) or mutable reference (`&mut T`).
  25 //!
  26 //! ```
  27 //! let my_num: i32 = 10;
  28 //! let my_num_ptr: *const i32 = &my_num;
  29 //! let mut my_speed: i32 = 88;
  30 //! let my_speed_ptr: *mut i32 = &mut my_speed;
  31 //! ```
  32 //!
  33 //! To get a pointer to a boxed value, dereference the box:
  34 //!
  35 //! ```
  36 //! let my_num: Box<i32> = Box::new(10);
  37 //! let my_num_ptr: *const i32 = &*my_num;
  38 //! let mut my_speed: Box<i32> = Box::new(88);
  39 //! let my_speed_ptr: *mut i32 = &mut *my_speed;
  40 //! ```
  41 //!
  42 //! This does not take ownership of the original allocation
  43 //! and requires no resource management later,
  44 //! but you must not use the pointer after its lifetime.
  45 //!
  46 //! ## 2. Consume a box (`Box<T>`).
  47 //!
  48 //! The `into_raw` function consumes a box and returns
  49 //! the raw pointer. It doesn't destroy `T` or deallocate any memory.
  50 //!
  51 //! ```
  52 //! # #![feature(alloc)]
  53 //! use std::boxed;
  54 //!
  55 //! unsafe {
  56 //!     let my_speed: Box<i32> = Box::new(88);
  57 //!     let my_speed: *mut i32 = boxed::into_raw(my_speed);
  58 //!
  59 //!     // By taking ownership of the original `Box<T>` though
  60 //!     // we are obligated to put it together later to be destroyed.
  61 //!     drop(Box::from_raw(my_speed));
  62 //! }
  63 //! ```
  64 //!
  65 //! Note that here the call to `drop` is for clarity - it indicates
  66 //! that we are done with the given value and it should be destroyed.
  67 //!
  68 //! ## 3. Get it from C.
  69 //!
  70 //! ```
  71 //! # #![feature(libc)]
  72 //! extern crate libc;
  73 //!
  74 //! use std::mem;
  75 //!
  76 //! fn main() {
  77 //!     unsafe {
  78 //!         let my_num: *mut i32 = libc::malloc(mem::size_of::<i32>() as libc::size_t) as *mut i32;
  79 //!         if my_num.is_null() {
  80 //!             panic!("failed to allocate memory");
  81 //!         }
  82 //!         libc::free(my_num as *mut libc::c_void);
  83 //!     }
  84 //! }
  85 //! ```
  86 //!
  87 //! Usually you wouldn't literally use `malloc` and `free` from Rust,
  88 //! but C APIs hand out a lot of pointers generally, so are a common source
  89 //! of raw pointers in Rust.
  90
  91 #![stable(feature = "rust1", since = "1.0.0")]
  92 #![doc(primitive = "pointer")]
  93
  94 use mem;
  95 use clone::Clone;
  96 use intrinsics;
  97 use ops::Deref;
  98 use core::fmt;
  99 use option::Option::{self, Some, None};
 100 use marker::{PhantomData, Send, Sized, Sync};
 101 use nonzero::NonZero;
 102
 103 use cmp::{PartialEq, Eq, Ord, PartialOrd};
 104 use cmp::Ordering::{self, Less, Equal, Greater};
 105
 106 // FIXME #19649: intrinsic docs don't render, so these have no docs :(
 107
 108 #[stable(feature = "rust1", since = "1.0.0")]
 109 pub use intrinsics::copy_nonoverlapping;
 110
 111 #[stable(feature = "rust1", since = "1.0.0")]
 112 pub use intrinsics::copy;
 113
 114 #[stable(feature = "rust1", since = "1.0.0")]
 115 pub use intrinsics::write_bytes;
 116
 117 /// Creates a null raw pointer.
 118 ///
 119 /// # Examples
 120 ///
 121 /// ```
 122 /// use std::ptr;
 123 ///
 124 /// let p: *const i32 = ptr::null();
 125 /// assert!(p.is_null());
 126 /// ```
 127 #[inline]
 128 #[stable(feature = "rust1", since = "1.0.0")]
 129 pub fn null<T>() -> *const T { 0 as *const T }
 130
 131 /// Creates a null mutable raw pointer.
 132 ///
 133 /// # Examples
 134 ///
 135 /// ```
 136 /// use std::ptr;
 137 ///
 138 /// let p: *mut i32 = ptr::null_mut();
 139 /// assert!(p.is_null());
 140 /// ```
 141 #[inline]
 142 #[stable(feature = "rust1", since = "1.0.0")]
 143 pub fn null_mut<T>() -> *mut T { 0 as *mut T }
 144
 145 /// Swaps the values at two mutable locations of the same type, without
 146 /// deinitialising either. They may overlap, unlike `mem::swap` which is
 147 /// otherwise equivalent.
 148 ///
 149 /// # Safety
 150 ///
 151 /// This is only unsafe because it accepts a raw pointer.
 152 #[inline]
 153 #[stable(feature = "rust1", since = "1.0.0")]
 154 pub unsafe fn swap<T>(x: *mut T, y: *mut T) {
 155     // Give ourselves some scratch space to work with
 156     let mut tmp: T = mem::uninitialized();
 157
 158     // Perform the swap
 159     copy_nonoverlapping(x, &mut tmp, 1);
 160     copy(y, x, 1); // `x` and `y` may overlap
 161     copy_nonoverlapping(&tmp, y, 1);
 162
 163     // y and t now point to the same thing, but we need to completely forget `tmp`
 164     // because it's no longer relevant.
 165     mem::forget(tmp);
 166 }
 167
 168 /// Replaces the value at `dest` with `src`, returning the old
 169 /// value, without dropping either.
 170 ///
 171 /// # Safety
 172 ///
 173 /// This is only unsafe because it accepts a raw pointer.
 174 /// Otherwise, this operation is identical to `mem::replace`.
 175 #[inline]
 176 #[stable(feature = "rust1", since = "1.0.0")]
 177 pub unsafe fn replace<T>(dest: *mut T, mut src: T) -> T {
 178     mem::swap(mem::transmute(dest), &mut src); // cannot overlap
 179     src
 180 }
 181
 182 /// Reads the value from `src` without moving it. This leaves the
 183 /// memory in `src` unchanged.
 184 ///
 185 /// # Safety
 186 ///
 187 /// Beyond accepting a raw pointer, this is unsafe because it semantically
 188 /// moves the value out of `src` without preventing further usage of `src`.
 189 /// If `T` is not `Copy`, then care must be taken to ensure that the value at
 190 /// `src` is not used before the data is overwritten again (e.g. with `write`,
 191 /// `zero_memory`, or `copy_memory`). Note that `*src = foo` counts as a use
 192 /// because it will attempt to drop the value previously at `*src`.
 193 #[inline(always)]
 194 #[stable(feature = "rust1", since = "1.0.0")]
 195 pub unsafe fn read<T>(src: *const T) -> T {
 196     let mut tmp: T = mem::uninitialized();
 197     copy_nonoverlapping(src, &mut tmp, 1);
 198     tmp
 199 }
 200
 201 /// Reads the value from `src` and nulls it out without dropping it.
 202 ///
 203 /// # Safety
 204 ///
 205 /// This is unsafe for the same reasons that `read` is unsafe.
 206 #[inline(always)]
 207 #[unstable(feature = "read_and_zero",
 208            reason = "may play a larger role in std::ptr future extensions")]
 209 pub unsafe fn read_and_zero<T>(dest: *mut T) -> T {
 210     // Copy the data out from `dest`:
 211     let tmp = read(&*dest);
 212
 213     // Now zero out `dest`:
 214     write_bytes(dest, 0, 1);
 215
 216     tmp
 217 }
 218
 219 /// Variant of read_and_zero that writes the specific drop-flag byte
 220 /// (which may be more appropriate than zero).
 221 #[inline(always)]
 222 #[unstable(feature = "filling_drop",
 223            reason = "may play a larger role in std::ptr future extensions")]
 224 pub unsafe fn read_and_drop<T>(dest: *mut T) -> T {
 225     // Copy the data out from `dest`:
 226     let tmp = read(&*dest);
 227
 228     // Now mark `dest` as dropped:
 229     write_bytes(dest, mem::POST_DROP_U8, 1);
 230
 231     tmp
 232 }
 233
 234 /// Overwrites a memory location with the given value without reading or
 235 /// dropping the old value.
 236 ///
 237 /// # Safety
 238 ///
 239 /// Beyond accepting a raw pointer, this operation is unsafe because it does
 240 /// not drop the contents of `dst`. This could leak allocations or resources,
 241 /// so care must be taken not to overwrite an object that should be dropped.
 242 ///
 243 /// This is appropriate for initializing uninitialized memory, or overwriting
 244 /// memory that has previously been `read` from.
 245 #[inline]
 246 #[stable(feature = "rust1", since = "1.0.0")]
 247 pub unsafe fn write<T>(dst: *mut T, src: T) {
 248     intrinsics::move_val_init(&mut *dst, src)
 249 }
 250
 251 #[stable(feature = "rust1", since = "1.0.0")]
 252 #[lang = "const_ptr"]
 253 impl<T: ?Sized> *const T {
 254     /// Returns true if the pointer is null.
 255     #[stable(feature = "rust1", since = "1.0.0")]
 256     #[inline]
 257     pub fn is_null(self) -> bool where T: Sized {
 258         self == 0 as *const T
 259     }
 260
 261     /// Returns `None` if the pointer is null, or else returns a reference to
 262     /// the value wrapped in `Some`.
 263     ///
 264     /// # Safety
 265     ///
 266     /// While this method and its mutable counterpart are useful for
 267     /// null-safety, it is important to note that this is still an unsafe
 268     /// operation because the returned value could be pointing to invalid
 269     /// memory.
 270     #[unstable(feature = "ptr_as_ref",
 271                reason = "Option is not clearly the right return type, and we \
 272                          may want to tie the return lifetime to a borrow of \
 273                          the raw pointer")]
 274     #[inline]
 275     pub unsafe fn as_ref<'a>(&self) -> Option<&'a T> where T: Sized {
 276         if self.is_null() {
 277             None
 278         } else {
 279             Some(&**self)
 280         }
 281     }
 282
 283     /// Calculates the offset from a pointer. `count` is in units of T; e.g. a
 284     /// `count` of 3 represents a pointer offset of `3 * sizeof::<T>()` bytes.
 285     ///
 286     /// # Safety
 287     ///
 288     /// Both the starting and resulting pointer must be either in bounds or one
 289     /// byte past the end of an allocated object. If either pointer is out of
 290     /// bounds or arithmetic overflow occurs then
 291     /// any further use of the returned value will result in undefined behavior.
 292     #[stable(feature = "rust1", since = "1.0.0")]
 293     #[inline]
 294     pub unsafe fn offset(self, count: isize) -> *const T where T: Sized {
 295         intrinsics::offset(self, count)
 296     }
 297 }
 298
 299 #[stable(feature = "rust1", since = "1.0.0")]
 300 #[lang = "mut_ptr"]
 301 impl<T: ?Sized> *mut T {
 302     /// Returns true if the pointer is null.
 303     #[stable(feature = "rust1", since = "1.0.0")]
 304     #[inline]
 305     pub fn is_null(self) -> bool where T: Sized {
 306         self == 0 as *mut T
 307     }
 308
 309     /// Returns `None` if the pointer is null, or else returns a reference to
 310     /// the value wrapped in `Some`.
 311     ///
 312     /// # Safety
 313     ///
 314     /// While this method and its mutable counterpart are useful for
 315     /// null-safety, it is important to note that this is still an unsafe
 316     /// operation because the returned value could be pointing to invalid
 317     /// memory.
 318     #[unstable(feature = "ptr_as_ref",
 319                reason = "Option is not clearly the right return type, and we \
 320                          may want to tie the return lifetime to a borrow of \
 321                          the raw pointer")]
 322     #[inline]
 323     pub unsafe fn as_ref<'a>(&self) -> Option<&'a T> where T: Sized {
 324         if self.is_null() {
 325             None
 326         } else {
 327             Some(&**self)
 328         }
 329     }
 330
 331     /// Calculates the offset from a pointer. `count` is in units of T; e.g. a
 332     /// `count` of 3 represents a pointer offset of `3 * sizeof::<T>()` bytes.
 333     ///
 334     /// # Safety
 335     ///
 336     /// The offset must be in-bounds of the object, or one-byte-past-the-end.
 337     /// Otherwise `offset` invokes Undefined Behaviour, regardless of whether
 338     /// the pointer is used.
 339     #[stable(feature = "rust1", since = "1.0.0")]
 340     #[inline]
 341     pub unsafe fn offset(self, count: isize) -> *mut T where T: Sized {
 342         intrinsics::offset(self, count) as *mut T
 343     }
 344
 345     /// Returns `None` if the pointer is null, or else returns a mutable
 346     /// reference to the value wrapped in `Some`.
 347     ///
 348     /// # Safety
 349     ///
 350     /// As with `as_ref`, this is unsafe because it cannot verify the validity
 351     /// of the returned pointer.
 352     #[unstable(feature = "ptr_as_ref",
 353                reason = "return value does not necessarily convey all possible \
 354                          information")]
 355     #[inline]
 356     pub unsafe fn as_mut<'a>(&self) -> Option<&'a mut T> where T: Sized {
 357         if self.is_null() {
 358             None
 359         } else {
 360             Some(&mut **self)
 361         }
 362     }
 363 }
 364
 365 // Equality for pointers
 366 #[stable(feature = "rust1", since = "1.0.0")]
 367 impl<T: ?Sized> PartialEq for *const T {
 368     #[inline]
 369     fn eq(&self, other: &*const T) -> bool { *self == *other }
 370 }
 371
 372 #[stable(feature = "rust1", since = "1.0.0")]
 373 impl<T: ?Sized> Eq for *const T {}
 374
 375 #[stable(feature = "rust1", since = "1.0.0")]
 376 impl<T: ?Sized> PartialEq for *mut T {
 377     #[inline]
 378     fn eq(&self, other: &*mut T) -> bool { *self == *other }
 379 }
 380
 381 #[stable(feature = "rust1", since = "1.0.0")]
 382 impl<T: ?Sized> Eq for *mut T {}
 383
 384 #[stable(feature = "rust1", since = "1.0.0")]
 385 impl<T: ?Sized> Clone for *const T {
 386     #[inline]
 387     fn clone(&self) -> *const T {
 388         *self
 389     }
 390 }
 391
 392 #[stable(feature = "rust1", since = "1.0.0")]
 393 impl<T: ?Sized> Clone for *mut T {
 394     #[inline]
 395     fn clone(&self) -> *mut T {
 396         *self
 397     }
 398 }
 399
 400 // Equality for extern "C" fn pointers
 401 mod externfnpointers {
 402     use mem;
 403     use cmp::PartialEq;
 404
 405     #[stable(feature = "rust1", since = "1.0.0")]
 406     impl<_R> PartialEq for extern "C" fn() -> _R {
 407         #[inline]
 408         fn eq(&self, other: &extern "C" fn() -> _R) -> bool {
 409             let self_: *const () = unsafe { mem::transmute(*self) };
 410             let other_: *const () = unsafe { mem::transmute(*other) };
 411             self_ == other_
 412         }
 413     }
 414     macro_rules! fnptreq {
 415         ($($p:ident),*) => {
 416             #[stable(feature = "rust1", since = "1.0.0")]
 417             impl<_R,$($p),*> PartialEq for extern "C" fn($($p),*) -> _R {
 418                 #[inline]
 419                 fn eq(&self, other: &extern "C" fn($($p),*) -> _R) -> bool {
 420                     let self_: *const () = unsafe { mem::transmute(*self) };
 421
 422                     let other_: *const () = unsafe { mem::transmute(*other) };
 423                     self_ == other_
 424                 }
 425             }
 426         }
 427     }
 428     fnptreq! { A }
 429     fnptreq! { A,B }
 430     fnptreq! { A,B,C }
 431     fnptreq! { A,B,C,D }
 432     fnptreq! { A,B,C,D,E }
 433 }
 434
 435 // Comparison for pointers
 436 #[stable(feature = "rust1", since = "1.0.0")]
 437 impl<T: ?Sized> Ord for *const T {
 438     #[inline]
 439     fn cmp(&self, other: &*const T) -> Ordering {
 440         if self < other {
 441             Less
 442         } else if self == other {
 443             Equal
 444         } else {
 445             Greater
 446         }
 447     }
 448 }
 449
 450 #[stable(feature = "rust1", since = "1.0.0")]
 451 impl<T: ?Sized> PartialOrd for *const T {
 452     #[inline]
 453     fn partial_cmp(&self, other: &*const T) -> Option<Ordering> {
 454         Some(self.cmp(other))
 455     }
 456
 457     #[inline]
 458     fn lt(&self, other: &*const T) -> bool { *self < *other }
 459
 460     #[inline]
 461     fn le(&self, other: &*const T) -> bool { *self <= *other }
 462
 463     #[inline]
 464     fn gt(&self, other: &*const T) -> bool { *self > *other }
 465
 466     #[inline]
 467     fn ge(&self, other: &*const T) -> bool { *self >= *other }
 468 }
 469
 470 #[stable(feature = "rust1", since = "1.0.0")]
 471 impl<T: ?Sized> Ord for *mut T {
 472     #[inline]
 473     fn cmp(&self, other: &*mut T) -> Ordering {
 474         if self < other {
 475             Less
 476         } else if self == other {
 477             Equal
 478         } else {
 479             Greater
 480         }
 481     }
 482 }
 483
 484 #[stable(feature = "rust1", since = "1.0.0")]
 485 impl<T: ?Sized> PartialOrd for *mut T {
 486     #[inline]
 487     fn partial_cmp(&self, other: &*mut T) -> Option<Ordering> {
 488         Some(self.cmp(other))
 489     }
 490
 491     #[inline]
 492     fn lt(&self, other: &*mut T) -> bool { *self < *other }
 493
 494     #[inline]
 495     fn le(&self, other: &*mut T) -> bool { *self <= *other }
 496
 497     #[inline]
 498     fn gt(&self, other: &*mut T) -> bool { *self > *other }
 499
 500     #[inline]
 501     fn ge(&self, other: &*mut T) -> bool { *self >= *other }
 502 }
 503
 504 /// A wrapper around a raw `*mut T` that indicates that the possessor
 505 /// of this wrapper owns the referent. This in turn implies that the
 506 /// `Unique<T>` is `Send`/`Sync` if `T` is `Send`/`Sync`, unlike a raw
 507 /// `*mut T` (which conveys no particular ownership semantics).  It
 508 /// also implies that the referent of the pointer should not be
 509 /// modified without a unique path to the `Unique` reference. Useful
 510 /// for building abstractions like `Vec<T>` or `Box<T>`, which
 511 /// internally use raw pointers to manage the memory that they own.
 512 #[unstable(feature = "unique", reason = "needs an RFC to flesh out design")]
 513 pub struct Unique<T: ?Sized> {
 514     pointer: NonZero<*const T>,
 515     _marker: PhantomData<T>,
 516 }
 517
 518 /// `Unique` pointers are `Send` if `T` is `Send` because the data they
 519 /// reference is unaliased. Note that this aliasing invariant is
 520 /// unenforced by the type system; the abstraction using the
 521 /// `Unique` must enforce it.
 522 #[unstable(feature = "unique")]
 523 unsafe impl<T: Send + ?Sized> Send for Unique<T> { }
 524
 525 /// `Unique` pointers are `Sync` if `T` is `Sync` because the data they
 526 /// reference is unaliased. Note that this aliasing invariant is
 527 /// unenforced by the type system; the abstraction using the
 528 /// `Unique` must enforce it.
 529 #[unstable(feature = "unique")]
 530 unsafe impl<T: Sync + ?Sized> Sync for Unique<T> { }
 531
 532 #[unstable(feature = "unique")]
 533 impl<T: ?Sized> Unique<T> {
 534     /// Creates a new `Unique`.
 535     pub unsafe fn new(ptr: *mut T) -> Unique<T> {
 536         Unique { pointer: NonZero::new(ptr), _marker: PhantomData }
 537     }
 538
 539     /// Dereferences the content.
 540     pub unsafe fn get(&self) -> &T {
 541         &**self.pointer
 542     }
 543
 544     /// Mutably dereferences the content.
 545     pub unsafe fn get_mut(&mut self) -> &mut T {
 546         &mut ***self
 547     }
 548 }
 549
 550 #[unstable(feature = "unique")]
 551 impl<T:?Sized> Deref for Unique<T> {
 552     type Target = *mut T;
 553
 554     #[inline]
 555     fn deref<'a>(&'a self) -> &'a *mut T {
 556         unsafe { mem::transmute(&*self.pointer) }
 557     }
 558 }
 559
 560 #[stable(feature = "rust1", since = "1.0.0")]
 561 impl<T> fmt::Pointer for Unique<T> {
 562     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 563         fmt::Pointer::fmt(&*self.pointer, f)
 564     }
 565 }