Add links to online OS documentation

Author: Thomasdezeeuw

src/lib.rs

@@ -115,6 +115,56 @@ macro_rules! from {
     };
 }
 
+/// Link to online documentation for (almost) all supported OSs.
+#[rustfmt::skip]
+macro_rules! man_links {
+    // Links to all OSs.
+    ($syscall: tt ( $section: tt ) ) => {
+        concat!(
+            man_links!(__ intro),
+            man_links!(__ unix $syscall($section)),
+            man_links!(__ windows $syscall($section)),
+        )
+    };
+    // Links to Unix-like OSs.
+    (unix: $syscall: tt ( $section: tt ) ) => {
+        concat!(
+            man_links!(__ intro),
+            man_links!(__ unix $syscall($section)),
+        )
+    };
+    // Links to Windows only.
+    (windows: $syscall: tt ( $section: tt ) ) => {
+        concat!(
+            man_links!(__ intro),
+            man_links!(__ windows $syscall($section)),
+        )
+    };
+    // Internals.
+    (__ intro) => {
+        "\n\nAdditional documentation can be found in manual of the OS:\n\n"
+    };
+    // List for Unix-like OSs.
+    (__ unix $syscall: tt ( $section: tt ) ) => {
+        concat!(
+            " * DragonFly BSD: <https://man.dragonflybsd.org/?command=", stringify!($syscall), "&section=", stringify!($section), ">\n",
+            " * FreeBSD: <https://www.freebsd.org/cgi/man.cgi?query=", stringify!($syscall), "&sektion=", stringify!($section), ">\n",
+            " * Linux: <https://man7.org/linux/man-pages/man", stringify!($section), "/", stringify!($syscall), ".", stringify!($section), ".html>\n",
+            " * macOS: <https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/", stringify!($syscall), ".", stringify!($section), ".html> (archived, actually for iOS)\n",
+            " * NetBSD: <https://man.netbsd.org/", stringify!($syscall), ".", stringify!($section), ">\n",
+            " * OpenBSD: <https://man.openbsd.org/", stringify!($syscall), ".", stringify!($section), ">\n",
+            " * iOS: <https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/", stringify!($syscall), ".", stringify!($section), ".html> (archived)\n",
+            " * illumos: <https://illumos.org/man/3SOCKET/", stringify!($syscall), ">\n",
+        )
+    };
+    // List for Window (so just Windows).
+    (__ windows $syscall: tt ( $section: tt ) ) => {
+        concat!(
+            " * Windows: <https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-", stringify!($syscall), ">\n",
+        )
+    };
+}
+
 mod sockaddr;
 mod socket;
 mod sockref;

src/socket.rs

@@ -121,9 +121,9 @@ impl Socket {
     ///
     /// On Unix-like systems, the close-on-exec flag is set on the new socket.
     /// Additionally, on Apple platforms `SOCK_NOSIGPIPE` is set. On Windows,
-    /// the socket is made non-inheritable.
-    ///
-    /// [`Socket::new_raw`] can be used if you don't want these flags to be set.
+    /// the socket is made non-inheritable. [`Socket::new_raw`] can be used if
+    /// you don't want these flags to be set.
+    #[doc = man_links!(socket(2))]
     pub fn new(domain: Domain, ty: Type, protocol: Option<Protocol>) -> io::Result<Socket> {
         let ty = set_common_type(ty);
         Socket::new_raw(domain, ty, protocol).and_then(set_common_flags)
@@ -142,8 +142,9 @@ impl Socket {
     ///
     /// This function corresponds to `socketpair(2)`.
     ///
-    /// This function sets the same flags as in done for [`Socket::new`],
+    /// This function sets the same flags as in done for [`Socket::new`].
     /// [`Socket::pair_raw`] can be used if you don't want to set those flags.
+    #[doc = man_links!(unix: socketpair(2))]
     #[cfg(any(doc, all(feature = "all", unix)))]
     #[cfg_attr(docsrs, doc(cfg(all(feature = "all", unix))))]
     pub fn pair(
@@ -177,6 +178,7 @@ impl Socket {
     ///
     /// This function directly corresponds to the `bind(2)` function on Windows
     /// and Unix.
+    #[doc = man_links!(bind(2))]
     pub fn bind(&self, address: &SockAddr) -> io::Result<()> {
         sys::bind(self.as_raw(), address)
     }
@@ -188,6 +190,7 @@ impl Socket {
     ///
     /// An error will be returned if `listen` or `connect` has already been
     /// called on this builder.
+    #[doc = man_links!(connect(2))]
     ///
     /// # Notes
     ///
@@ -242,6 +245,7 @@ impl Socket {
     ///
     /// An error will be returned if `listen` or `connect` has already been
     /// called on this builder.
+    #[doc = man_links!(listen(2))]
     pub fn listen(&self, backlog: c_int) -> io::Result<()> {
         sys::listen(self.as_raw(), backlog)
     }
@@ -253,6 +257,7 @@ 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))]
     pub fn accept(&self) -> io::Result<(Socket, SockAddr)> {
         // Use `accept4` on platforms that support it.
         #[cfg(any(
@@ -299,6 +304,10 @@ impl Socket {
 
     /// Returns the socket address of the local half of this socket.
     ///
+    /// This function directly corresponds to the `getsockname(2)` function on
+    /// Windows and Unix.
+    #[doc = man_links!(getsockname(2))]
+    ///
     /// # Notes
     ///
     /// Depending on the OS this may return an error if the socket is not
@@ -311,6 +320,10 @@ impl Socket {
 
     /// Returns the socket address of the remote peer of this socket.
     ///
+    /// This function directly corresponds to the `getpeername(2)` function on
+    /// Windows and Unix.
+    #[doc = man_links!(getpeername(2))]
+    ///
     /// # Notes
     ///
     /// This returns an error if the socket is not [`connect`ed].
@@ -336,8 +349,7 @@ impl Socket {
     /// On Windows this uses `WSA_FLAG_NO_HANDLE_INHERIT` setting inheriting to
     /// false.
     ///
-    /// On Windows this can **not** be used function cannot be used on a
-    /// QOS-enabled socket, see
+    /// On Windows this function cannot be used on a QOS-enabled socket, see
     /// <https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaduplicatesocketw>.
     pub fn try_clone(&self) -> io::Result<Socket> {
         sys::try_clone(self.as_raw()).map(Socket::from_raw)
@@ -359,6 +371,7 @@ impl Socket {
     ///
     /// This function will cause all pending and future I/O on the specified
     /// portions to return immediately with an appropriate value.
+    #[doc = man_links!(shutdown(2))]
     pub fn shutdown(&self, how: Shutdown) -> io::Result<()> {
         sys::shutdown(self.as_raw(), how)
     }
@@ -368,6 +381,7 @@ impl Socket {
     ///
     /// The [`connect`] method will connect this socket to a remote address.
     /// This method might fail if the socket is not connected.
+    #[doc = man_links!(recv(2))]
     ///
     /// [`connect`]: Socket::connect
     ///
@@ -419,6 +433,7 @@ impl Socket {
     /// In addition to the number of bytes read, this function returns the flags
     /// for the received message. See [`RecvFlags`] for more information about
     /// the returned flags.
+    #[doc = man_links!(recvmsg(2))]
     ///
     /// [`recv`]: Socket::recv
     /// [`connect`]: Socket::connect
@@ -484,6 +499,7 @@ impl Socket {
 
     /// Receives data from the socket. On success, returns the number of bytes
     /// read and the address from whence the data came.
+    #[doc = man_links!(recvfrom(2))]
     ///
     /// # Safety
     ///
@@ -510,6 +526,7 @@ impl Socket {
     /// Receives data from the socket. Returns the amount of bytes read, the
     /// [`RecvFlags`] and the remote address from the data is coming. Unlike
     /// [`recv_from`] this allows passing multiple buffers.
+    #[doc = man_links!(recvmsg(2))]
     ///
     /// [`recv_from`]: Socket::recv_from
     ///
@@ -573,6 +590,7 @@ impl Socket {
     /// been connected.
     ///
     /// On success returns the number of bytes that were sent.
+    #[doc = man_links!(send(2))]
     pub fn send(&self, buf: &[u8]) -> io::Result<usize> {
         self.send_with_flags(buf, 0)
     }
@@ -594,6 +612,7 @@ impl Socket {
 
     /// Identical to [`send_vectored`] but allows for specification of arbitrary
     /// flags to the underlying `sendmsg`/`WSASend` call.
+    #[doc = man_links!(sendmsg(2))]
     ///
     /// [`send_vectored`]: Socket::send_vectored
     #[cfg(not(target_os = "redox"))]
@@ -621,6 +640,7 @@ impl Socket {
     /// number of bytes written.
     ///
     /// This is typically used on UDP or datagram-oriented sockets.
+    #[doc = man_links!(sendto(2))]
     pub fn send_to(&self, buf: &[u8], addr: &SockAddr) -> io::Result<usize> {
         self.send_to_with_flags(buf, addr, 0)
     }
@@ -640,6 +660,7 @@ impl Socket {
 
     /// Send data to a peer listening on `addr`. Returns the amount of bytes
     /// written.
+    #[doc = man_links!(sendmsg(2))]
     #[cfg(not(target_os = "redox"))]
     #[cfg_attr(docsrs, doc(cfg(not(target_os = "redox"))))]
     pub fn send_to_vectored(&self, bufs: &[IoSlice<'_>], addr: &SockAddr) -> io::Result<usize> {
@@ -737,6 +758,7 @@ pub enum InterfaceIndexOrAddress {
 /// Additional documentation can be found in documentation of the OS.
 /// * Linux: <https://man7.org/linux/man-pages/man7/socket.7.html>
 /// * Windows: <https://docs.microsoft.com/en-us/windows/win32/winsock/sol-socket-socket-options>
+//#[doc = man_links!(setsockopt(2))]
 impl Socket {
     /// Get the value of the `SO_BROADCAST` option for this socket.
     ///

src/sys/unix.rs

@@ -1053,6 +1053,7 @@ impl crate::Socket {
     /// This function will block the calling thread until a new connection is
     /// established. When established, the corresponding `Socket` and the remote
     /// peer's address will be returned.
+    #[doc = man_links!(unix: accept4(2))]
     #[cfg(all(
         feature = "all",
         any(
@@ -1806,6 +1807,7 @@ impl crate::Socket {
     /// Different OSs support different kinds of `file`s, see the OS
     /// documentation for what kind of files are supported. Generally *regular*
     /// files are supported by all OSs.
+    #[doc = man_links!(unix: sendfile(2))]
     ///
     /// The `offset` is the absolute offset into the `file` to use as starting
     /// point.