std: Update documentation of seek_write on Windows

Currently the documentation of `FileExt::seek_write` on Windows
indicates that writes beyond the end of the file leave intermediate
bytes uninitialized. This commentary dates back to the original
inclusion of these functions in  (wow blast from the past!). At
the time the functionality here was implemented using `WriteFile`, but
nowadays the `NtWriteFile` method is used instead. The documentation for
`NtWriteFile` explicitly states:

> If Length and ByteOffset specify a write operation past the current
> end-of-file mark, NtWriteFile automatically extends the file and updates
> the end-of-file mark; any bytes that are not explicitly written between
> such old and new end-of-file marks are defined to be zero.

This commentary has had a downstream impact in the `system-interface`
crate where it tries to handle this by explicitly writing zeros, but I
don't believe that's necessary any more. I'm sending a PR upstream here
to avoid future confusion and codify that zeros are written in the
intermediate bytes matching what Windows currently provides.
This commit is contained in:
Alex Crichton 2024-01-28 11:24:27 -08:00
parent 7a34091eed
commit b85b2a783b

@ -59,7 +59,7 @@ pub trait FileExt {
/// function, it is set to the end of the write.
///
/// When writing beyond the end of the file, the file is appropriately
/// extended and the intermediate bytes are left uninitialized.
/// extended and the intermediate bytes are set to zero.
///
/// Note that similar to `File::write`, it is not an error to return a
/// short write. When returning from such a short write, the file pointer