Document Linux kernel handoff in std::io::copy and std::fs::copy

[rust.git] / library / std / src / fs.rs

diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs
index d4e103ab525e8b880ebe1750e8826235bc32c090..9daf694d68b78848b407bbf736044e79992a77e4 100644 (file)
--- a/library/std/src/fs.rs
+++ b/library/std/src/fs.rs
@@ -1729,10 +1729,16 @@ pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()>
 /// This function currently corresponds to the `open` function in Unix
 /// with `O_RDONLY` for `from` and `O_WRONLY`, `O_CREAT`, and `O_TRUNC` for `to`.
 /// `O_CLOEXEC` is set for returned file descriptors.
+///
+/// On Linux (including Android), this function attempts to use `copy_file_range(2)`,
+/// and falls back to reading and writing if that is not possible.
+///
 /// On Windows, this function currently corresponds to `CopyFileEx`. Alternate
 /// NTFS streams are copied but only the size of the main stream is returned by
-/// this function. On MacOS, this function corresponds to `fclonefileat` and
-/// `fcopyfile`.
+/// this function.
+///
+/// On MacOS, this function corresponds to `fclonefileat` and `fcopyfile`.
+///
 /// Note that, this [may change in the future][changes].
 ///
 /// [changes]: io#platform-specific-behavior