Add docs for set_no_peercred

Author: Berrysoft

src/socket.rs

@@ -200,6 +200,9 @@ impl Socket {
     /// non-blocking mode before calling this function), socket option can't be
     /// set *while connecting*. This will cause errors on Windows. Socket
     /// options can be safely set before and after connecting the socket.
+    ///
+    /// On Cygwin, a Unix domain socket connect blocks until the server accepts
+    /// it. If the behavior is not expected, try [`Socket::set_no_peercred`].
     pub fn connect(&self, address: &SockAddr) -> io::Result<()> {
         sys::connect(self.as_raw(), address)
     }
@@ -260,6 +263,11 @@ impl Socket {
     /// This function sets the same flags as in done for [`Socket::new`],
     /// [`Socket::accept_raw`] can be used if you don't want to set those flags.
     #[doc = man_links!(accept(2))]
+    ///
+    /// # Notes
+    ///
+    /// On Cygwin, a Unix domain socket connect blocks until the server accepts
+    /// it. If the behavior is not expected, try [`Socket::set_no_peercred`].
     pub fn accept(&self) -> io::Result<(Socket, SockAddr)> {
         // Use `accept4` on platforms that support it.
         #[cfg(any(

src/sys/unix.rs

@@ -1502,7 +1502,15 @@ impl crate::Socket {
     }
 
     /// Sets `SO_PEERCRED` to null on the socket.
-    /// It disables the initial handshake of unix domain sockets.
+    /// This is a Cygwin extension.
+    ///
+    /// Normally the Unix domain sockets of Cygwin are implemented by TCP sockets,
+    /// so it performs a handshake on `connect` and `accept`, to verify the remote
+    /// connection and exchange peer cred info. Therefore, `connect` blocks until
+    /// the server `accept`s it. This option turns off the handshake. Both client
+    /// and server should turn it off to let `connect` returns immediately.
+    ///
+    /// See also: the [mailing list](https://inbox.sourceware.org/cygwin/TYCPR01MB10926FF8926CA63704867ADC8F8AA2@TYCPR01MB10926.jpnprd01.prod.outlook.com/)
     #[cfg(target_os = "cygwin")]
     pub fn set_no_peercred(&self) -> io::Result<()> {
         syscall!(setsockopt(