Document what a "dangling pointer" is

[Urgau]

Location

There are several places this applies, e.g.:

• std::ptr::dangling
• std::ptr::from_ref (in the examples)
• dangling_pointers_from_temporaries lint

Summary

We have several place in the standard library or as part of lints where we use the term "dangling pointer" without defining it anywhere.

We should have a place where we define what that is, ideally in the standard library, in it's own section, maybe under std::ptr, so it can be referenced elsewhere.

It should probably have a definition, followed by some bad examples (and maybe how to fix them).

Wikipedia has article on the subject, I don't know if it could serve as a base for our documentation but it may be worth checking it.

Steps

• Add std documentation
• Update existing std docs
• Update lints diagnostics

[saethlin]

cc @rust-lang/opsem

[RalfJung]

Also see rust-lang/unsafe-code-guidelines#478 (but note that some things changed since the issue was opened so part of the information there is outdated).

[theemathas]

The reference has a definition of dangling pointers.

[RalfJung]

Right, so somewhat confusingly ptr::dangling on a ZST does actually produce a non-dangling pointer.

[theemathas]

The documentation for ptr::dangling even explicitly says that it produces a dangling pointer (which is maybe false?). And then it goes to say that "the pointer value may potentially represent a valid pointer to a T" (which is false for non-ZST types, due to provenance).

[theemathas]

Documentation from the reference:

A reference/pointer is “dangling” if not all of the bytes it points to are part of the same live allocation (so in particular they all have to be part of some allocation).
If the size is 0, then the pointer is trivially never “dangling” (even if it is a null pointer).

This implies that a pointer points to a range of addresses, depending on the type, and whether a pointer is dangling depends on the type.

Documentation from std::ptr:

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.

This implies that whether a pointer is dangling or not doesn't depend on the type.

These two definitions are contradictory.

[RalfJung]

"may potentially" is definitely true, it doesn't say "will always" after all.

But yeah "is dangling" in the ptr::dangling docs uses a different definition of "dangling" than the reference. There are two reasonable definitions and we don't have a clear term to distinguish them:

• A pointer that doesn't point to allocated memory
• A pointer to type T that doesn't point to at least size_of::<T> bytes of allocated memory

We need to choose a different term for one of these.