From 54e9a6a994986ba1e6ef779dbe0bc67222d75f1b Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Sat, 14 Feb 2026 14:00:45 +0100 Subject: [PATCH] refactor 'valid for read/write' definition: exclude null --- library/core/src/ptr/mod.rs | 61 +++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs index cb75cd9a2a578..48e1e206a313e 100644 --- a/library/core/src/ptr/mod.rs +++ b/library/core/src/ptr/mod.rs @@ -15,22 +15,19 @@ //! The precise rules for validity are not determined yet. The guarantees that are //! provided at this point are very minimal: //! -//! * For memory accesses of [size zero][zst], *every* pointer is valid, including the [null] -//! pointer. The following points are only concerned with non-zero-sized accesses. -//! * A [null] pointer is *never* valid. -//! * For a pointer to be valid, it is necessary, but not always sufficient, that the pointer be -//! *dereferenceable*. The [provenance] of the pointer is used to determine which [allocation] -//! it is derived from; a pointer is dereferenceable if the memory range of the given size -//! starting at the pointer is entirely contained within the bounds of that allocation. Note +//! * A [null] pointer is *never* valid for reads/writes. +//! * For memory accesses of [size zero][zst], *every* non-null pointer is valid for reads/writes. +//! The following points are only concerned with non-zero-sized accesses. +//! * For a pointer to be valid for reads/writes, it is necessary, but not always sufficient, that +//! the pointer be *dereferenceable*. The [provenance] of the pointer is used to determine which +//! [allocation] it is derived from; a pointer is dereferenceable if the memory range of the given +//! size starting at the pointer is entirely contained within the bounds of that allocation. Note //! that in Rust, every (stack-allocated) variable is considered a separate allocation. //! * All accesses performed by functions in this module are *non-atomic* in the sense //! of [atomic operations] used to synchronize between threads. This means it is //! undefined behavior to perform two concurrent accesses to the same location from different -//! threads unless both accesses only read from memory. Notice that this explicitly -//! includes [`read_volatile`] and [`write_volatile`]: Volatile accesses cannot -//! be used for inter-thread synchronization, regardless of whether they are acting on -//! Rust memory or not. -//! * The result of casting a reference to a pointer is valid for as long as the +//! threads unless both accesses only read from memory. +//! * The result of casting a reference to a pointer is valid for reads/writes for as long as the //! underlying allocation is live and no reference (just raw pointers) is used to //! access the same memory. That is, reference and pointer accesses cannot be //! interleaved. @@ -41,6 +38,13 @@ //! information, see the [book] as well as the section in the reference devoted //! to [undefined behavior][ub]. //! +//! Note that some operations such as [`read`] and [`write`][`write()`] do allow null pointers if +//! the total size of the access is zero. However, other operations internally convert pointers into +//! references. Therefore, the general notion of "valid for reads/writes" excludes null pointers, +//! and the specific operations that permit null pointers mention that as an exception. Furthermore, +//! [`read_volatile`] and [`write_volatile`] can be used in even more situations; see their +//! documentation for details. +//! //! We say that a pointer is "dangling" if it is not valid for any non-zero-sized accesses. This //! means out-of-bounds pointers, pointers to freed memory, null pointers, and pointers created with //! [`NonNull::dangling`] are all dangling. @@ -450,9 +454,9 @@ mod mut_ptr; /// /// Behavior is undefined if any of the following conditions are violated: /// -/// * `src` must be [valid] for reads of `count * size_of::()` bytes. +/// * `src` must be [valid] for reads of `count * size_of::()` bytes or that number must be 0. /// -/// * `dst` must be [valid] for writes of `count * size_of::()` bytes. +/// * `dst` must be [valid] for writes of `count * size_of::()` bytes or that number must be 0. /// /// * Both `src` and `dst` must be properly aligned. /// @@ -568,11 +572,11 @@ pub const unsafe fn copy_nonoverlapping(src: *const T, dst: *mut T, count: us /// /// Behavior is undefined if any of the following conditions are violated: /// -/// * `src` must be [valid] for reads of `count * size_of::()` bytes. +/// * `src` must be [valid] for reads of `count * size_of::()` bytes or that number must be 0. /// -/// * `dst` must be [valid] for writes of `count * size_of::()` bytes, and must remain valid even -/// when `src` is read for `count * size_of::()` bytes. (This means if the memory ranges -/// overlap, the `dst` pointer must not be invalidated by `src` reads.) +/// * `dst` must be [valid] for writes of `count * size_of::()` bytes or that number must be 0, +/// and `dst` must remain valid even when `src` is read for `count * size_of::()` bytes. (This +/// means if the memory ranges overlap, the `dst` pointer must not be invalidated by `src` reads.) /// /// * Both `src` and `dst` must be properly aligned. /// @@ -1508,7 +1512,7 @@ unsafe fn swap_nonoverlapping_bytes(x: *mut u8, y: *mut u8, bytes: NonZero(dst: *mut T, src: T) -> T { ) => ub_checks::maybe_is_aligned_and_not_null(addr, align, is_zst) ); if T::IS_ZST { - // `dst` may be valid for read and writes while also being null, in which case we cannot - // call `mem::replace`. However, we also don't have to actually do anything since there - // isn't actually any data to be copied anyway. All values of type `T` are - // bit-identical, so we can just return `src` here. + // If `T` is a ZST, `dst` is allowed to be null. However, we also don't have to actually + // do anything since there isn't actually any data to be copied anyway. All values of + // type `T` are bit-identical, so we can just return `src` here. return src; } mem::replace(&mut *dst, src) @@ -1572,7 +1575,7 @@ pub const unsafe fn replace(dst: *mut T, src: T) -> T { /// /// Behavior is undefined if any of the following conditions are violated: /// -/// * `src` must be [valid] for reads. +/// * `src` must be [valid] for reads or `T` must be a ZST. /// /// * `src` must be properly aligned. Use [`read_unaligned`] if this is not the /// case. @@ -1824,7 +1827,7 @@ pub const unsafe fn read_unaligned(src: *const T) -> T { /// /// Behavior is undefined if any of the following conditions are violated: /// -/// * `dst` must be [valid] for writes. +/// * `dst` must be [valid] for writes or `T` must be a ZST. /// /// * `dst` must be properly aligned. Use [`write_unaligned`] if this is not the /// case. @@ -2047,8 +2050,8 @@ pub const unsafe fn write_unaligned(dst: *mut T, src: T) { /// /// Behavior is undefined if any of the following conditions are violated: /// -/// * `src` must be either [valid] for reads, or it must point to memory outside of all Rust -/// allocations and reading from that memory must: +/// * `src` must be either [valid] for reads, or `T` must be a ZST, or `src` must point to memory +/// outside of all Rust allocations and reading from that memory must: /// - not trap, and /// - not cause any memory inside a Rust allocation to be modified. /// @@ -2135,8 +2138,8 @@ pub unsafe fn read_volatile(src: *const T) -> T { /// /// Behavior is undefined if any of the following conditions are violated: /// -/// * `dst` must be either [valid] for writes, or it must point to memory outside of all Rust -/// allocations and writing to that memory must: +/// * `dst` must be either [valid] for writes, or `T` must be a ZST, or `dst` must point to memory +/// outside of all Rust allocations and writing to that memory must: /// - not trap, and /// - not cause any memory inside a Rust allocation to be modified. ///