Skip to content

Commit e40585f

Browse files
ecstatic-morseRalfJung
authored andcommitted
Remove definiton of valid pointer
The enumerated list of conditions is replaced by an explanation that rust doesn't have a formal memory model. It does say that pointers created directly from references are guaranteed to be valid, and links to both the "Unsafe Code" section of the book and the "Undefined Behavior" section of the reference.
1 parent 30122e9 commit e40585f

File tree

1 file changed

+14
-7
lines changed

1 file changed

+14
-7
lines changed

src/libcore/ptr.rs

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,20 +17,27 @@
1717
//! # Safety
1818
//!
1919
//! Many functions in this module take raw pointers as arguments and dereference
20-
//! them. For this to be safe, these pointers must be valid. A valid pointer
21-
//! is one that satisfies **all** of the following conditions:
20+
//! them. For this to be safe, these pointers must be valid. However, because
21+
//! rust does not yet have a formal memory model, determining whether an
22+
//! arbitrary pointer is a valid one can be tricky. One thing is certain:
23+
//! creating a raw pointer from a reference (e.g. `&x as *const _`) *always*
24+
//! results in a valid pointer. By exploiting this—and by taking care when
25+
//! using [pointer arithmetic]—users can be confident in the correctness of
26+
//! their unsafe code.
2227
//!
23-
//! * The pointer is not null.
24-
//! * The pointer is not dangling (it does not point to memory which has been
25-
//! freed).
26-
//! * The pointer satisfies [LLVM's pointer aliasing rules].
28+
//! For more information on dereferencing raw pointers, see the both the [book]
29+
//! and the section in the reference devoted to [undefined behavior][ub].
30+
//!
31+
//! ## Alignment
2732
//!
2833
//! Valid pointers are not necessarily properly aligned. However, most functions
2934
//! require their arguments to be properly aligned, and will explicitly state
3035
//! this requirement in the `Safety` section. Notable exceptions to this are
3136
//! [`read_unaligned`] and [`write_unaligned`].
3237
//!
33-
//! [LLVM's pointer aliasing rules]: https://llvm.org/docs/LangRef.html#pointer-aliasing-rules
38+
//! [ub]: ../../reference/behavior-considered-undefined.html
39+
//! [book]: ../../book/second-edition/ch19-01-unsafe-rust.html#dereferencing-a-raw-pointer
40+
//! [pointer arithmetic]: ../../std/primitive.pointer.html#method.offset
3441
//! [`read_unaligned`]: ./fn.read_unaligned.html
3542
//! [`write_unaligned`]: ./fn.write_unaligned.html
3643

0 commit comments

Comments
 (0)