Auto merge of #97178 - sunfishcode:ownedfd-and-dup, r=joshtriplett

Add a `BorrowedFd::try_clone_to_owned` and accompanying documentation

Add a `BorrowedFd::try_clone_to_owned`, which returns a new `OwnedFd` sharing the underlying file description. And similar for `BorrowedHandle` and `BorrowedSocket` on WIndows.

This is similar to the existing `OwnedFd::try_clone`, but it's named differently to reflect that it doesn't return `Result<Self, ...>`. I'm open to suggestions for better names.

Also, extend the `unix::io` documentation to mention that `dup` is permitted on `BorrowedFd`.

This was originally requsted [here](https://github.com/rust-lang/rust/issues/88564#issuecomment-910786081). At the time I wasn't sure whether it was desirable, but it does have uses and it helps clarify the API. The documentation previously didn't rule out using `dup` on a `BorrowedFd`, but the API only offered convenient ways to do it from an `OwnedFd`. With this patch, the API allows one to do `try_clone` on any type where it's permitted.

1 files changed, 1 insertions, 1 deletions

diff --git a/library/std/src/sys/windows/handle.rs b/library/std/src/sys/windows/handle.rs
index ef9a8bd6900..1e7b6e1eab0 100644
--- a/library/std/src/sys/windows/handle.rs
+++ b/library/std/src/sys/windows/handle.rs
@@ -218,7 +218,7 @@ impl Handle {
         inherit: bool,
         options: c::DWORD,
     ) -> io::Result<Self> {
-        Ok(Self(self.0.duplicate(access, inherit, options)?))
+        Ok(Self(self.0.as_handle().duplicate(access, inherit, options)?))
     }
 
     /// Performs a synchronous read.