From e7dc177442e7c91ea0c691a992a634ac879db16f Mon Sep 17 00:00:00 2001 From: darklyspaced Date: Thu, 20 Jul 2023 11:27:13 +0800 Subject: [PATCH 1/2] fix docs & example for FileExt::write_at --- library/std/src/os/unix/fs.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/library/std/src/os/unix/fs.rs b/library/std/src/os/unix/fs.rs index 1e1c369310547..358ab33fffdfb 100644 --- a/library/std/src/os/unix/fs.rs +++ b/library/std/src/os/unix/fs.rs @@ -149,7 +149,14 @@ pub trait FileExt { /// Note that similar to [`File::write`], it is not an error to return a /// short write. /// + /// # Bug + /// On some systems, due to a [bug] with [`pwrite64`] (the underlying + /// syscall), files opened with the `O_APPEND` flag fail to respect the + /// offset parameter, always appending to the end of the file instead. + /// /// [`File::write`]: fs::File::write + /// [`pwrite64`]: https://man7.org/linux/man-pages/man2/pwrite.2.html + /// [bug]: https://man7.org/linux/man-pages/man2/pwrite.2.html#BUGS /// /// # Examples /// @@ -159,7 +166,7 @@ pub trait FileExt { /// use std::os::unix::prelude::FileExt; /// /// fn main() -> io::Result<()> { - /// let file = File::open("foo.txt")?; + /// let file = File::create("foo.txt")?; /// /// // We now write at the offset 10. /// file.write_at(b"sushi", 10)?; From 7d17a263d1a6e46700f65d378a9ae7280a2b3371 Mon Sep 17 00:00:00 2001 From: darklyspaced Date: Thu, 20 Jul 2023 14:25:50 +0800 Subject: [PATCH 2/2] added a problematic example --- library/std/src/os/unix/fs.rs | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/library/std/src/os/unix/fs.rs b/library/std/src/os/unix/fs.rs index 358ab33fffdfb..19d9e89a63154 100644 --- a/library/std/src/os/unix/fs.rs +++ b/library/std/src/os/unix/fs.rs @@ -150,9 +150,31 @@ pub trait FileExt { /// short write. /// /// # Bug - /// On some systems, due to a [bug] with [`pwrite64`] (the underlying - /// syscall), files opened with the `O_APPEND` flag fail to respect the - /// offset parameter, always appending to the end of the file instead. + /// On some systems, `write_at` utilises [`pwrite64`] to write to files. + /// However, this syscall has a [bug] where files opened with the `O_APPEND` + /// flag fail to respect the offset parameter, always appending to the end + /// of the file instead. + /// + /// It is possible to inadvertantly set this flag, like in the example below. + /// Therefore, it is important to be vigilant while changing options to mitigate + /// unexpected behaviour. + /// + /// ```no_run + /// use std::fs::File; + /// use std::io; + /// use std::os::unix::prelude::FileExt; + /// + /// fn main() -> io::Result<()> { + /// // Open a file with the append option (sets the `O_APPEND` flag) + /// let file = File::options().append(true).open("foo.txt")?; + /// + /// // We attempt to write at offset 10; instead appended to EOF + /// file.write_at(b"sushi", 10)?; + /// + /// // foo.txt is 5 bytes long instead of 15 + /// Ok(()) + /// } + /// ``` /// /// [`File::write`]: fs::File::write /// [`pwrite64`]: https://man7.org/linux/man-pages/man2/pwrite.2.html