From 93e9f5e96692f46c279c5d8d8096c613a9728925 Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Thu, 24 Mar 2022 21:44:39 -0700 Subject: [PATCH] Document Linux kernel handoff in std::io::copy and std::fs::copy --- library/std/src/fs.rs | 10 ++++++++-- library/std/src/io/copy.rs | 6 ++++++ 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs index d4e103ab525..9daf694d68b 100644 --- a/library/std/src/fs.rs +++ b/library/std/src/fs.rs @@ -1729,10 +1729,16 @@ pub fn rename, Q: AsRef>(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 diff --git a/library/std/src/io/copy.rs b/library/std/src/io/copy.rs index 6ab96662305..d446af0dad3 100644 --- a/library/std/src/io/copy.rs +++ b/library/std/src/io/copy.rs @@ -39,6 +39,12 @@ /// Ok(()) /// } /// ``` +/// +/// # Platform-specific behavior +/// +/// On Linux (including Android), this function uses `copy_file_range(2)`, +/// `sendfile(2)` or `splice(2)` syscalls to move data directly between file +/// descriptors if possible. #[stable(feature = "rust1", since = "1.0.0")] pub fn copy(reader: &mut R, writer: &mut W) -> Result where -- 2.44.0