Change:
/// Note that similar to [`File::write`], it is not an error to return a /// short write. /// <ins> /// # Bug /// 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(()) /// } /// ``` /// </ins> /// [`File::write`]: fs::File::write <ins> /// [`pwrite64`]: https://man7.org/linux/man-pages/man2/pwrite.2.html /// [bug]: https://man7.org/linux/man-pages/man2/pwrite.2.html#BUGS </ins> /// /// # Examples ///

Discussion:
<!-- the function from doesn't work as described and the example fails --I'm pretty new to rust and I'm working on a small project where I need to write into a file some data at various offsets, so the function seems to perfectly fit my need. So I tried this code (with is the provided example): and I do I expected to see this happen: a in the current directory with a size of 15 bytes Instead, this happened: Error: Os { code: 2, kind: NotFound, message: "No such file or directory" } So, I modifed the filename to (in order to have an absolute path). I got the same error. So, I created the file with Then I got the error: So, I add the line to get some info on the file Then I got: So, the file is open read-only, I searched and modified the code to: Then I got: and finally no error (on stdout), But the file is only 5-byte long whereas I expected it to be 15-byte long. And checking content with gives: The final code is and you need to manually create the file before running the binary. <!-- If you're using the stable version of the compiler, you should also check if the bug also exists in the beta or nightly versions. --: <!-- Include a backtrace in the code block by setting in your environment. E.g. . --<details<summaryBacktrace</summary<p</p</details<!-- TRIAGEBOTSTART --<!-- TRIAGEBOTASSIGNSTART --<!-- TRIAGEBOTASSIGNDATASTARTTRIAGEBOTASSIGNDATAEND --<!-- TRIAGEBOTASSIGNEND --<!-- TRIAGEBOTEND --
Wow those docs are terrible, how did that happen? We can immediately patch the docs to code that actually would work to write to a file, but we need to define what "extended appropriately" means. i.e. Is this intended behavior? But perhaps more importantly, we need to figure out why the hell we have doctest examples that don't actually work and what can we do to fix that?
Yeah it's weird that we have a non-working example. That should be fixed asap. It looks like it was copy/pasted from but not updated to use or something like that. I'll mark this as help wanted. Fixing that should not be controversial.

The issue with the final code in the OP is that it opens the file in append only mode. The docs do not cover this case at all so I can't say what the intended behaviour is. I guess is really incompatible with append only because it needs to have some knowledge of the real file position in order to work as expected.
( for the doc fix part, anyways. )
It does explain that returning short writes is valid, so I guess the behavior exhibited in the append-only case presented here is technically acceptable behavior.
On Linux, just calls which documents this:
There was a to fix this via a flag on , but that didn't get merged...
We discussed this in the libs-api meeting. It seems that there are 2 actionable items here, both in the documentation: The example in needs to be fixed to use (write mode) instead of (read mode). The documentation for should link to to indicate that, on some platforms, files opened in append mode ignore the position passed in and always append to the end of the file.
claim