docs: document close-on-exec behavior in socket try_clone methods

AprilNEA · AprilNEA · commit 6e5b89aaf4ff · 2026-01-17T17:27:21.000+08:00
Document that `try_clone()` sets the close-on-exec flag on duplicated sockets, addressing issue #47946. On Unix, `F_DUPFD_CLOEXEC` is used to atomically duplicate the file descriptor with the close-on-exec flag set. On Windows, the duplicated socket is created without `HANDLE_FLAG_INHERIT`. This affects: - `TcpStream::try_clone()` - `TcpListener::try_clone()` - `UdpSocket::try_clone()` - `UnixStream::try_clone()` - `UnixListener::try_clone()` - `UnixDatagram::try_clone()`
diff --git a/library/std/src/net/tcp.rs b/library/std/src/net/tcp.rs
@@ -253,6 +253,18 @@ impl TcpStream {
     /// data, and options set on one stream will be propagated to the other
     /// stream.
     ///
+    /// # Platform-specific behavior
+    ///
+    /// On Unix, this method uses `F_DUPFD_CLOEXEC` to duplicate the file descriptor
+    /// atomically with the close-on-exec flag set. This means the duplicated socket
+    /// will be automatically closed when calling `exec()`, and thus will not be
+    /// available in child processes created via [`Command`].
+    ///
+    /// On Windows, the duplicated socket is created without the `HANDLE_FLAG_INHERIT`
+    /// flag, so it will similarly not be inherited by child processes.
+    ///
+    /// [`Command`]: crate::process::Command
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -806,6 +818,18 @@ impl TcpListener {
     /// object references. Both handles can be used to accept incoming
     /// connections and options set on one listener will affect the other.
     ///
+    /// # Platform-specific behavior
+    ///
+    /// On Unix, this method uses `F_DUPFD_CLOEXEC` to duplicate the file descriptor
+    /// atomically with the close-on-exec flag set. This means the duplicated socket
+    /// will be automatically closed when calling `exec()`, and thus will not be
+    /// available in child processes created via [`Command`].
+    ///
+    /// On Windows, the duplicated socket is created without the `HANDLE_FLAG_INHERIT`
+    /// flag, so it will similarly not be inherited by child processes.
+    ///
+    /// [`Command`]: crate::process::Command
+    ///
     /// # Examples
     ///
     /// ```no_run
diff --git a/library/std/src/net/udp.rs b/library/std/src/net/udp.rs
@@ -259,6 +259,18 @@ impl UdpSocket {
     /// object references. Both handles will read and write the same port, and
     /// options set on one socket will be propagated to the other.
     ///
+    /// # Platform-specific behavior
+    ///
+    /// On Unix, this method uses `F_DUPFD_CLOEXEC` to duplicate the file descriptor
+    /// atomically with the close-on-exec flag set. This means the duplicated socket
+    /// will be automatically closed when calling `exec()`, and thus will not be
+    /// available in child processes created via [`Command`].
+    ///
+    /// On Windows, the duplicated socket is created without the `HANDLE_FLAG_INHERIT`
+    /// flag, so it will similarly not be inherited by child processes.
+    ///
+    /// [`Command`]: crate::process::Command
+    ///
     /// # Examples
     ///
     /// ```no_run
diff --git a/library/std/src/os/unix/net/datagram.rs b/library/std/src/os/unix/net/datagram.rs
@@ -261,6 +261,13 @@ impl UnixDatagram {
     /// object references. Both handles can be used to accept incoming
     /// connections and options set on one side will affect the other.
     ///
+    /// This method uses `F_DUPFD_CLOEXEC` to duplicate the file descriptor
+    /// atomically with the close-on-exec flag set. This means the duplicated socket
+    /// will be automatically closed when calling `exec()`, and thus will not be
+    /// available in child processes created via [`Command`].
+    ///
+    /// [`Command`]: crate::process::Command
+    ///
     /// # Examples
     ///
     /// ```no_run
diff --git a/library/std/src/os/unix/net/listener.rs b/library/std/src/os/unix/net/listener.rs
@@ -188,6 +188,13 @@ impl UnixListener {
     /// object references. Both handles can be used to accept incoming
     /// connections and options set on one listener will affect the other.
     ///
+    /// This method uses `F_DUPFD_CLOEXEC` to duplicate the file descriptor
+    /// atomically with the close-on-exec flag set. This means the duplicated socket
+    /// will be automatically closed when calling `exec()`, and thus will not be
+    /// available in child processes created via [`Command`].
+    ///
+    /// [`Command`]: crate::process::Command
+    ///
     /// # Examples
     ///
     /// ```no_run
diff --git a/library/std/src/os/unix/net/stream.rs b/library/std/src/os/unix/net/stream.rs
@@ -185,6 +185,13 @@ impl UnixStream {
     /// data, and options set on one stream will be propagated to the other
     /// stream.
     ///
+    /// This method uses `F_DUPFD_CLOEXEC` to duplicate the file descriptor
+    /// atomically with the close-on-exec flag set. This means the duplicated socket
+    /// will be automatically closed when calling `exec()`, and thus will not be
+    /// available in child processes created via [`Command`].
+    ///
+    /// [`Command`]: crate::process::Command
+    ///
     /// # Examples
     ///
     /// ```no_run
