Slightly reformat `std::fs::remove_dir_all` error docs
To make the error cases easier to spot on a quick glance, as I've been bitten by this a couple of times already 💀
cc #137230.
Add a bullet point to `std::fs::copy`
I needed to copy a file but I got the following error:
```
Os { code: 2, kind: NotFound, message: "No such file or directory" }
```
After read the documentation, I though the error was generated by the `from` parameter, forgetting the `to` part. Anyway, I got the error because the parent folder of `to` didn't exist.
Even if the documentation explicitly saying `but is not limited to just these cases`, I would like to add this case because I spent 3 hours around it.
This PR just wants to put a mention about it.
Locking documentation updates
- Reword file lock documentation to clarify advisory vs mandatory. Remove the
word "advisory", and make it more explicit that the lock may be advisory or
mandatory depending on platform.
- Document that locking a file fails on Windows if the file is opened only for append
Improve examples for file locking
The `lock` and `try_lock` documentation states that "if the file not open for writing, it is unspecified whether this function returns an error." With this change, the examples use `File::create` instead of `File::open`, eliminating the possibility of someone blindly copying code with unspecified behavior.
Windows: remove readonly files
When calling `remove_file`, we shouldn't fail to delete readonly files. As the test makes clear, this make the Windows behaviour consistent with other platforms. This also makes us internally consistent with `remove_dir_all`.
try-job: x86_64-msvc-ext1
Add notes to each method stating that locks get dropped on close.
Clarify the return values of the try methods: they're only defined if
the lock is held via a *different* file handle/descriptor. That goes
along with the documentation that calling them while holding a lock via
the *same* file handle/descriptor may deadlock.
Document the behavior of unlock if no lock is held.
Win: Use POSIX rename semantics for `std::fs::rename` if available
Windows 10 1601 introduced `FileRenameInfoEx` as well as `FILE_RENAME_FLAG_POSIX_SEMANTICS`, allowing for atomic renaming and renaming if the target file is has already been opened with `FILE_SHARE_DELETE`, in which case the file gets renamed on disk while the open file handle still refers to the old file, just like in POSIX. This resolves#123985, where atomic renaming proved difficult to impossible due to race conditions.
If `FileRenameInfoEx` isn't available due to missing support from the underlying filesystem or missing OS support, the renaming is retried with `FileRenameInfo`, which matches the behavior of `MoveFileEx`.
This PR also manually replicates parts of `MoveFileEx`'s internal logic, as reverse-engineered from the disassembly: If the source file is a reparse point and said reparse point is a mount point, the mount point itself gets renamed; otherwise the reparse point is resolved and the result renamed.
Notes:
- Currently, the `win7` target doesn't bother with `FileRenameInfoEx` at all; it's probably desirable to remove that special casing and try `FileRenameInfoEx` anyway if it doesn't exist, in case the binary is run on newer OS versions.
Fixes#123985
This is explicitly mentioned for std::fs::remove_file's documentation,
but not in the aforementioned function.
It is more likely for a slightly lazy programmer to believe that
removing a file would work and that they do not have to distinguish
between directories (with contents) and files themself, because of the
function's recursive nature and how it distinguishes between files and
directories when removing them.
Implement file_lock feature
This adds lock(), lock_shared(), try_lock(), try_lock_shared(), and unlock() to File gated behind the file_lock feature flag
This is the initial implementation of https://github.com/rust-lang/rust/issues/130994 for Unix and Windows platforms. I will follow it up with an implementation for WASI preview 2
Windows 10 1601 introduced `FileRenameInfoEx` as well as
`FILE_RENAME_FLAG_POSIX_SEMANTICS`, allowing for atomic renaming. If it
isn't supported, we fall back to `FileRenameInfo`.
This commit also replicates `MoveFileExW`'s behavior of checking whether
the source file is a mount point and moving the mount point instead of
resolving the target path.
Remove macOS 10.10 dynamic linker bug workaround
Rust's current minimum macOS version is 10.12, so the hack can be removed. This PR also updates the `remove_dir_all` docs to reflect that all supported macOS versions are protected against TOCTOU race conditions (the fallback implementation was already removed in #127683).
try-job: dist-x86_64-apple
try-job: dist-aarch64-apple
try-job: dist-apple-various
try-job: aarch64-apple
try-job: x86_64-apple-1
Document behavior of `create_dir_all` wrt. empty path
The behavior makes sense because `Path::new("one_component").parent() == Some(Path::new(""))`, so if one naively wants to create the parent directory for a file to be written, it simply works.
Closes#105108 by documenting the current behavior.
