From 95ccdb11dab922fa8d6b1b7a24acd82b0b30f071 Mon Sep 17 00:00:00 2001 From: Geoffroy Couprie Date: Fri, 14 May 2021 15:12:33 +0200 Subject: [PATCH] add an example to explain std::io::Read::read returning 0 in some cases the example focuses on Linux, but that should be enough to explain how the behaviour can change --- library/std/src/io/mod.rs | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index 9f43379aff7..7d9228be5a2 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -526,7 +526,12 @@ pub trait Read { /// /// 1. This reader has reached its "end of file" and will likely no longer /// be able to produce bytes. Note that this does not mean that the - /// reader will *always* no longer be able to produce bytes. + /// reader will *always* no longer be able to produce bytes. As an example, + /// on Linux, this method will call the `recv` syscall for a [`TcpStream`], + /// where returning zero indicates the connection was shut down correctly. While + /// for [`File`], it is possible to reach the end of file and get zero as result, + /// but if more data is appended to the file, future calls to `read` will return + /// more data. /// 2. The buffer specified was 0 bytes in length. /// /// It is not an error if the returned value `n` is smaller than the buffer size, @@ -568,6 +573,7 @@ pub trait Read { /// /// [`Ok(n)`]: Ok /// [`File`]: crate::fs::File + /// [`TcpStream`]: crate::net::TcpStream /// /// ```no_run /// use std::io;