Document whether dereferencing a raw pointer requires alignment

[ExpHP]

I am referring to the following operation, built into the language:

let x: *const u32 = unimplemented!();

unsafe { *x }

I checked all over:

The pointer primitive docs don't mention alignment.

The std::ptr module states:

Valid raw pointers as defined above are not necessarily properly aligned (where "proper" alignment is defined by the pointee type, i.e., *const T must be aligned to mem::align_of::<T>()). However, most functions require their arguments to be properly aligned, and will explicitly state this requirement in their documentation. Notable exceptions to this are read_unaligned and write_unaligned.

This is clearly banking on the fact that every function is documented, but raw pointer dereference is a built-in operation and therefore has no documentation aside from the (previously mentioned) pointer primitive page.

I checked The Rust Programming Language, Second Edition, one of the top google results (note: the google result is actually for 1.30.0). The string "align" does not appear.

I checked The Rust Reference. Nothing.

---

With no mention of alignment literally anywhere, you would think: Surely it must not be required, then, right?

Well, I checked the issue tracker, and according to this issue it sounds like alignment is required.

[RalfJung]

Alignment is definitely required for raw pointer reads and writes.

I think the reason why it is not said anywhere is because * on a reference and a raw pointer are the same operation. That operation requires alignment, as is mentioned (I hope) when talking about references. Since it is the same operation, "of course" it also requires alignment when working on a raw pointer.

But you are right, this should probably be documented better. While at it, the drop behavior of writing to a raw pointer should also be called out.

[RalfJung]

@ExpHP these days, the reference says that it is UB when the program is...

Dereferencing (using the * operator on) a dangling or unaligned raw pointer.

That should help, I think. But it is probably also a good idea to repeat this in the primitive type docs.

[RalfJung]

Ah, and the docs for the pointer type now state:

However, when a raw pointer is dereferenced (using the * operator), it must be non-null and aligned.

So, I think we can close this issue.