> +//! User pointers.
> +//!
> +//! C header: [`include/linux/uaccess.h`](../../../../include/linux/uaccess.h)
> +
nit: could this be using srctree-relative links?
> +/// The maximum length of a operation using `copy_[from|to]_user`.
nit: 'a' -> 'an'
> +///
> +/// If a usize is not greater than this constant, then casting it to `c_ulong`
> +/// is guaranteed to be lossless.
nit: could this be `usize` or [`usize`]. Maybe would also be clearer to
say "... a value of type [`usize`] is smaller than ..."
> +///
> +/// These APIs are designed to make it difficult to accidentally write TOCTOU
> +/// bugs. Every time you read from a memory location, the pointer is advanced by
Maybe makes sense to also introduce the abbreviation TOCTOU in the type
documentation when it is first used.
> + /// Reads the entirety of the user slice.
> + ///
> + /// Returns `EFAULT` if the address does not currently point to
> + /// mapped, readable memory.
> + pub fn read_all(self) -> Result<Vec<u8>> {
> + self.reader().read_all()
> + }
If I understand it correctly, the function will return `EFAULT` if _any_
address in the interval `[self.0, self.0 + self.1)` does not point to
mapped, readable memory. Maybe the docs could be more explicit.
> + // Since this is not a pointer to a valid object in our program,
> + // we cannot use `add`, which has C-style rules for defined
> + // behavior.
> + self.0 = self.0.wrapping_add(len);
If I understand it correctly, you are using 'valid object' to refer to
an 'allocated object' [1] as this is what the `add` method's docs
refer to [2]. In that case it might be better to use the latter term as
it has a defined meaning. Also see [3] and [4] which are about making it
more precise.
[1]: https://doc.rust-lang.org/core/ptr/index.html#allocated-object
[2]: https://doc.rust-lang.org/core/primitive.pointer.html#method.add
[3]: https://github.com/rust-lang/rust/pull/116675
[4]: https://github.com/rust-lang/unsafe-code-guidelines/issues/465
