Add support for receiving ancillary data

src/socket.rs

@@ -442,6 +442,29 @@ impl Socket {
         sys::recv(self.as_raw(), buf, flags)
     }
 
+    /// Receives normal and ancillary data on the socket from the remote address to which it is
+    /// connected by setting the `msg_control` field with syscall recvmsg.
+    ///
+    /// In addition to the data received with [`recv`], this method also returns ancillary data.
+    /// To be noted that the ancillary data is not associated with out-of-band (OOB) data.
+    ///
+    /// [`recv`]: Socket::recv
+    #[doc = man_links!(recvmsg(2))]
+    #[cfg(not(target_os = "redox"))]
+    #[cfg_attr(docsrs, doc(cfg(target_os = "redox")))]
+    pub fn recv_with_ancillary_data(
+        &self,
+        buf: &mut [MaybeUninit<u8>],
+        ancillary_data: &mut [MaybeUninit<u8>],
+    ) -> io::Result<(usize, RecvFlags)> {
+        sys::recv_vectored_with_ancillary_data(
+            self.as_raw(),
+            &mut [MaybeUninitSlice::new(buf)],
+            ancillary_data,
+            0,
+        )
+    }
+
     /// Receives data on the socket from the remote address to which it is
     /// connected. Unlike [`recv`] this allows passing multiple buffers.
     ///
@@ -498,6 +521,20 @@ impl Socket {
         sys::recv_vectored(self.as_raw(), bufs, flags)
     }
 
+    /// Identical to [`recv_with_ancillary_data`] but allows passing multiple buffers and flags.
+    ///
+    /// [`recv_with_ancillary_data`]: Socket::recv_with_ancillary_data
+    #[cfg(not(target_os = "redox"))]
+    #[cfg_attr(docsrs, doc(cfg(target_os = "redox")))]
+    pub fn recv_vectored_with_ancillary_data_and_flags(
+        &self,
+        bufs: &mut [MaybeUninitSlice<'_>],
+        ancillary_data: &mut [MaybeUninit<u8>],
+        flags: c_int,
+    ) -> io::Result<(usize, RecvFlags)> {
+        sys::recv_vectored_with_ancillary_data(self.as_raw(), bufs, ancillary_data, flags)
+    }
+
     /// Receives data on the socket from the remote adress to which it is
     /// connected, without removing that data from the queue. On success,
     /// returns the number of bytes peeked.

src/sys/unix.rs

@@ -950,7 +950,18 @@ pub(crate) fn recv_vectored(
     bufs: &mut [crate::MaybeUninitSlice<'_>],
     flags: c_int,
 ) -> io::Result<(usize, RecvFlags)> {
-    recvmsg(fd, ptr::null_mut(), bufs, flags).map(|(n, _, recv_flags)| (n, recv_flags))
+    recvmsg(fd, ptr::null_mut(), bufs, &mut [], flags).map(|(n, _, recv_flags)| (n, recv_flags))
+}
+
+#[cfg(not(target_os = "redox"))]
+pub(crate) fn recv_vectored_with_ancillary_data(
+    fd: Socket,
+    bufs: &mut [crate::MaybeUninitSlice<'_>],
+    ancillary_data: &mut [MaybeUninit<u8>],
+    flags: c_int,
+) -> io::Result<(usize, RecvFlags)> {
+    recvmsg(fd, ptr::null_mut(), bufs, ancillary_data, flags)
+        .map(|(n, _, recv_flags)| (n, recv_flags))
 }
 
 #[cfg(not(target_os = "redox"))]
@@ -963,7 +974,7 @@ pub(crate) fn recv_from_vectored(
     // manually.
     unsafe {
         SockAddr::try_init(|storage, len| {
-            recvmsg(fd, storage, bufs, flags).map(|(n, addrlen, recv_flags)| {
+            recvmsg(fd, storage, bufs, &mut [], flags).map(|(n, addrlen, recv_flags)| {
                 // Set the correct address length.
                 *len = addrlen;
                 (n, recv_flags)
@@ -980,6 +991,7 @@ fn recvmsg(
     fd: Socket,
     msg_name: *mut sockaddr_storage,
     bufs: &mut [crate::MaybeUninitSlice<'_>],
+    ancillary_data: &mut [MaybeUninit<u8>],
     flags: c_int,
 ) -> io::Result<(usize, libc::socklen_t, RecvFlags)> {
     let msg_namelen = if msg_name.is_null() {
@@ -993,6 +1005,8 @@ fn recvmsg(
     msg.msg_namelen = msg_namelen;
     msg.msg_iov = bufs.as_mut_ptr().cast();
     msg.msg_iovlen = min(bufs.len(), IovLen::MAX as usize) as IovLen;
+    msg.msg_control = ancillary_data.as_mut_ptr().cast();
+    msg.msg_controllen = ancillary_data.len() as _;
     syscall!(recvmsg(fd, &mut msg, flags))
         .map(|n| (n as usize, msg.msg_namelen, RecvFlags(msg.msg_flags)))
 }

tests/socket.rs

@@ -592,6 +592,46 @@ fn out_of_band() {
     assert_eq!(unsafe { assume_init(&buf[..n]) }, DATA);
 }
 
+#[test]
+#[cfg(not(target_os = "redox"))]
+fn recv_ancillary_data() {
+    use libc::setsockopt;
+
+    let (socket_a, socket_b) = udp_pair_connected();
+    let enabled = 1 as u32;
+    let ret = unsafe {
+        setsockopt(
+            socket_b.as_raw_fd(),
+            libc::IPPROTO_IPV6,
+            libc::IPV6_RECVPKTINFO,
+            &enabled as *const u32 as *const libc::c_void,
+            mem::size_of::<u32>() as libc::socklen_t,
+        )
+    };
+    assert_eq!(ret, 0);
+
+    let sent = socket_a.send(DATA).unwrap();
+    assert_eq!(sent, DATA.len());
+
+    let mut buf = [MaybeUninit::<u8>::uninit(); 16];
+    let mut ancillary = [MaybeUninit::<u8>::uninit(); 128];
+    let (received, _) = socket_b
+        .recv_with_ancillary_data(&mut buf, &mut ancillary)
+        .unwrap();
+    assert_eq!(received, DATA.len());
+    assert_eq!(unsafe { assume_init(&buf[..received]) }, DATA);
+
+    let ancillary = unsafe { assume_init(&ancillary[..]) };
+    let cmsg_len = ancillary[0..core::mem::size_of::<libc::size_t>()]
+        .try_into()
+        .map(usize::from_le_bytes)
+        .unwrap();
+    assert_eq!(
+        cmsg_len,
+        core::mem::size_of::<libc::cmsghdr>() + core::mem::size_of::<libc::in6_pktinfo>()
+    );
+}
+
 #[test]
 #[cfg(not(target_os = "redox"))] // cfg of `udp_pair_unconnected()`
 fn udp_peek_sender() {