From 9dfda62763a4462407bf76b916b1808aed57401a Mon Sep 17 00:00:00 2001
From: Jannis Harder <me@jix.one>
Date: Mon, 8 Mar 2021 11:58:05 +0100
Subject: [PATCH] Clarify docs for Read::read's return value
---
library/std/src/io/mod.rs | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs
index 17002e3b8602..6abb300054af 100644
--- a/library/std/src/io/mod.rs
+++ b/library/std/src/io/mod.rs
@@ -514,8 +514,8 @@ pub trait Read {
/// waiting for data, but if an object needs to block for a read and cannot,
/// it will typically signal this via an [`Err`] return value.
///
- /// If the return value of this method is [`Ok(n)`], then it must be
- /// guaranteed that `0 <= n <= buf.len()`. A nonzero `n` value indicates
+ /// If the return value of this method is [`Ok(n)`], then implementations must
+ /// guarantee that `0 <= n <= buf.len()`. A nonzero `n` value indicates
/// that the buffer `buf` has been filled in with `n` bytes of data from this
/// source. If `n` is `0`, then it can indicate one of two scenarios:
///
@@ -529,6 +529,11 @@ pub trait Read {
/// This may happen for example because fewer bytes are actually available right now
/// (e. g. being close to end-of-file) or because read() was interrupted by a signal.
///
+ /// As this trait is safe to implement, callers cannot rely on `n <= buf.len()` for safety.
+ /// Extra care needs to be taken when `unsafe` functions are used to access the read bytes.
+ /// Callers have to ensure that no unchecked out-of-bounds accesses are possible even if
+ /// `n > buf.len()`.
+ ///
/// No guarantees are provided about the contents of `buf` when this
/// function is called, implementations cannot rely on any property of the
/// contents of `buf` being true. It is recommended that *implementations*