From 00bae8774cf0a464b3ba88c546d4a615bb53206a Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Wed, 12 Jun 2019 23:23:34 +0200 Subject: [PATCH] note some safety concerns of raw-ptr-to-ref casts --- src/libcore/ptr/mod.rs | 38 +++++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/src/libcore/ptr/mod.rs b/src/libcore/ptr/mod.rs index 80ac67d8eb57c..8f026a5b7d8dd 100644 --- a/src/libcore/ptr/mod.rs +++ b/src/libcore/ptr/mod.rs @@ -984,8 +984,17 @@ impl *const T { /// operation because the returned value could be pointing to invalid /// memory. /// + /// When calling this method, you have to ensure that if the pointer is + /// non-NULL, then it is properly aligned, dereferencable (for the whole + /// size of `T`) and points to an initialized instance of `T`. This applies + /// even if the result of this method is unused! + /// (The part about being initialized is not yet fully decided, but until + /// it is, the only safe approach is to ensure that they are indeed initialized.) + /// /// Additionally, the lifetime `'a` returned is arbitrarily chosen and does - /// not necessarily reflect the actual lifetime of the data. + /// not necessarily reflect the actual lifetime of the data. It is up to the + /// caller to ensure that for the duration of this lifetime, the memory this + /// pointer points to does not get written to outside of `UnsafeCell`. /// /// # Examples /// @@ -1610,8 +1619,17 @@ impl *mut T { /// operation because the returned value could be pointing to invalid /// memory. /// + /// When calling this method, you have to ensure that if the pointer is + /// non-NULL, then it is properly aligned, dereferencable (for the whole + /// size of `T`) and points to an initialized instance of `T`. This applies + /// even if the result of this method is unused! + /// (The part about being initialized is not yet fully decided, but until + /// it is, the only safe approach is to ensure that they are indeed initialized.) + /// /// Additionally, the lifetime `'a` returned is arbitrarily chosen and does - /// not necessarily reflect the actual lifetime of the data. + /// not necessarily reflect the actual lifetime of the data. It is up to the + /// caller to ensure that for the duration of this lifetime, the memory this + /// pointer points to does not get written to outside of `UnsafeCell`. /// /// # Examples /// @@ -1755,10 +1773,24 @@ impl *mut T { /// /// # Safety /// - /// As with `as_ref`, this is unsafe because it cannot verify the validity + /// As with [`as_ref`], this is unsafe because it cannot verify the validity /// of the returned pointer, nor can it ensure that the lifetime `'a` /// returned is indeed a valid lifetime for the contained data. /// + /// When calling this method, you have to ensure that if the pointer is + /// non-NULL, then it is properly aligned, dereferencable (for the whole + /// size of `T`) and points to an initialized instance of `T`. This applies + /// even if the result of this method is unused! + /// (The part about being initialized is not yet fully decided, but until + /// it is the only safe approach is to ensure that they are indeed initialized.) + /// + /// Additionally, the lifetime `'a` returned is arbitrarily chosen and does + /// not necessarily reflect the actual lifetime of the data. It is up to the + /// caller to ensure that for the duration of this lifetime, the memory this + /// pointer points to does not get accessed through any other pointer. + /// + /// [`as_ref`]: #method.as_ref + /// /// # Examples /// /// Basic usage: