mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #111940 - zirconium-n:io-read-doc-change, r=thomcc

Browse Source 
Clarify safety concern of `io::Read::read` is only relevant in unsafe code

We have this clarification note in other similar place like [Iterator::size_hint](https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html#method.size_hint).

The lack of clarification might lead to confusion to Rust beginners. [Relevant URLO post](https://users.rust-lang.org/t/can-read-overflow-a-buffer/94347).
This commit is contained in:
Matthias Krüger 2023-05-26 08:24:08 +02:00 committed by GitHub
commit 2daecf7c45
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 4 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
library/std/src/io/mod.rs
View File

@ -593,7 +593,8 @@ pub trait Read {
/// This may happen for example because fewer bytes are actually available right now /// 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. /// (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. /// As this trait is safe to implement, callers in unsafe code cannot rely on
/// `n <= buf.len()` for safety.
/// Extra care needs to be taken when `unsafe` functions are used to access the read bytes. /// 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 /// Callers have to ensure that no unchecked out-of-bounds accesses are possible even if
/// `n > buf.len()`. /// `n > buf.len()`.
@ -603,8 +604,8 @@ pub trait Read {
/// contents of `buf` being true. It is recommended that *implementations* /// contents of `buf` being true. It is recommended that *implementations*
/// only write data to `buf` instead of reading its contents. /// only write data to `buf` instead of reading its contents.
/// ///
/// Correspondingly, however, *callers* of this method must not assume any guarantees /// Correspondingly, however, *callers* of this method in unsafe code must not assume
/// about how the implementation uses `buf`. The trait is safe to implement, /// any guarantees about how the implementation uses `buf`. The trait is safe to implement,
/// so it is possible that the code that's supposed to write to the buffer might also read /// so it is possible that the code that's supposed to write to the buffer might also read
/// from it. It is your responsibility to make sure that `buf` is initialized /// from it. It is your responsibility to make sure that `buf` is initialized
/// before calling `read`. Calling `read` with an uninitialized `buf` (of the kind one /// before calling `read`. Calling `read` with an uninitialized `buf` (of the kind one