Return new RecvFlags struct with vectored I/O.

The `RecvFlags` struct replaces the boolean to indicate if messages are
truncated.

Author: de-vri-es

src/lib.rs

@@ -237,3 +237,60 @@ impl From<Protocol> for c_int {
         p.0
     }
 }
+
+/// Flags for incoming messages.
+///
+/// Flags provide additional information about incoming messages.
+#[cfg(not(target_os = "redox"))]
+#[derive(Copy, Clone, Eq, PartialEq)]
+pub struct RecvFlags(c_int);
+
+#[cfg(not(target_os = "redox"))]
+impl RecvFlags {
+    /// Check if the message terminates a record.
+    ///
+    /// Not all socket types support the notion of records.
+    /// For socket types that do support it (such as [`SEQPACKET`][Type::SEQPACKET]),
+    /// a record is terminated by sending a message with the end-of-record flag set.
+    ///
+    /// On Unix this corresponds to the MSG_EOR flag.
+    #[cfg(unix)]
+    pub fn is_end_of_record(self) -> bool {
+        self.0 & sys::MSG_EOR != 0
+    }
+
+    /// Check if the message contains out-of-band data.
+    ///
+    /// This is useful for protocols where you receive out-of-band data
+    /// mixed in with the normal data stream.
+    ///
+    /// On Unix this corresponds to the MSG_OOB flag.
+    #[cfg(unix)]
+    pub fn is_out_of_band(self) -> bool {
+        self.0 & sys::MSG_OOB != 0
+    }
+
+    /// Check if the message contains a truncated datagram.
+    ///
+    /// This flag is only used for datagram-based sockets,
+    /// not for stream sockets.
+    ///
+    /// On Unix this corresponds to the MSG_TRUNC flag.
+    /// On Windows this corresponds to the WSAEMSGSIZE error code.
+    pub fn is_trunctated(self) -> bool {
+        self.0 & sys::MSG_TRUNC != 0
+    }
+}
+
+#[cfg(not(target_os = "redox"))]
+impl std::fmt::Debug for RecvFlags {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let mut dbg = f.debug_struct("RecvFlags");
+        #[cfg(unix)]
+        dbg.field("is_end_of_record", &self.is_end_of_record());
+        #[cfg(unix)]
+        dbg.field("is_out_of_band", &self.is_out_of_band());
+        dbg.field("is_trunctated", &self.is_trunctated());
+        dbg.finish()
+    }
+}

src/socket.rs

@@ -21,6 +21,8 @@ use libc::MSG_OOB;
 use winapi::um::winsock2::MSG_OOB;
 
 use crate::sys;
+#[cfg(not(target_os = "redox"))]
+use crate::RecvFlags;
 use crate::{Domain, Protocol, SockAddr, Type};
 
 /// Owned wrapper around a system socket.
@@ -264,16 +266,16 @@ impl Socket {
 
     /// Identical to [`recv_with_flags`] but reads into a slice of buffers.
     ///
-    /// In addition to the number of bytes read, this function a flag to indicate if a received datagram was truncated.
-    /// For stream sockets, the flag has no meaning.
+    /// In addition to the number of bytes read, this function return the flags for the received message.
+    /// See [`RecvFlags`] for more information about the flags.
     ///
     /// [`recv_with_flags`]: #method.recv_with_flags
     #[cfg(not(target_os = "redox"))]
     pub fn recv_vectored(
         &self,
         bufs: &mut [IoSliceMut<'_>],
         flags: i32,
-    ) -> io::Result<(usize, bool)> {
+    ) -> io::Result<(usize, RecvFlags)> {
         self.inner().recv_vectored(bufs, flags)
     }
 
@@ -319,16 +321,16 @@ impl Socket {
 
     /// Identical to [`recv_from_with_flags`] but reads into a slice of buffers.
     ///
-    /// In addition to the number of bytes read, this function a flag to indicate if a received datagram was truncated.
-    /// For stream sockets, the flag has no meaning.
+    /// In addition to the number of bytes read, this function return the flags for the received message.
+    /// See [`RecvFlags`] for more information about the flags.
     ///
     /// [`recv_from_with_flags`]: #method.recv_from_with_flags
     #[cfg(not(target_os = "redox"))]
     pub fn recv_from_vectored(
         &self,
         bufs: &mut [IoSliceMut<'_>],
         flags: i32,
-    ) -> io::Result<(usize, bool, SockAddr)> {
+    ) -> io::Result<(usize, RecvFlags, SockAddr)> {
         self.inner().recv_from_vectored(bufs, flags)
     }
 

src/sys/unix.rs

@@ -25,6 +25,8 @@ use std::{cmp, fmt, io, mem};
 
 use libc::{self, c_void, ssize_t};
 
+#[cfg(not(target_os = "redox"))]
+use crate::RecvFlags;
 use crate::{Domain, Type};
 
 pub use libc::c_int;
@@ -81,6 +83,10 @@ macro_rules! syscall {
     }};
 }
 
+// Re-export message flags for the RecvFlags struct.
+#[cfg(not(target_os = "redox"))]
+pub(crate) use libc::{MSG_EOR, MSG_OOB, MSG_TRUNC};
+
 #[cfg(any(target_os = "android", all(target_os = "linux", target_env = "gnu")))]
 type IovLen = usize;
 
@@ -509,7 +515,7 @@ impl Socket {
         &self,
         bufs: &mut [IoSliceMut<'_>],
         flags: c_int,
-    ) -> io::Result<(usize, bool)> {
+    ) -> io::Result<(usize, RecvFlags)> {
         let mut msg = libc::msghdr {
             msg_name: std::ptr::null_mut(),
             msg_namelen: 0,
@@ -521,16 +527,15 @@ impl Socket {
         };
 
         let n = syscall!(recvmsg(self.fd, &mut msg as *mut _, flags))?;
-        let truncated = msg.msg_flags & libc::MSG_TRUNC != 0;
-        Ok((n as usize, truncated))
+        Ok((n as usize, RecvFlags(msg.msg_flags)))
     }
 
     #[cfg(not(target_os = "redox"))]
     pub fn recv_from_vectored(
         &self,
         bufs: &mut [IoSliceMut<'_>],
         flags: c_int,
-    ) -> io::Result<(usize, bool, SockAddr)> {
+    ) -> io::Result<(usize, RecvFlags, SockAddr)> {
         let mut storage: libc::sockaddr_storage = unsafe { mem::zeroed() };
         let mut msg = libc::msghdr {
             msg_name: &mut storage as *mut libc::sockaddr_storage as *mut c_void,
@@ -543,10 +548,9 @@ impl Socket {
         };
 
         let n = syscall!(recvmsg(self.fd, &mut msg as *mut _, flags))?;
-        let truncated = msg.msg_flags & libc::MSG_TRUNC != 0;
         let addr =
             unsafe { SockAddr::from_raw_parts(&storage as *const _ as *const _, msg.msg_namelen) };
-        Ok((n as usize, truncated, addr))
+        Ok((n as usize, RecvFlags(msg.msg_flags), addr))
     }
 
     pub fn send(&self, buf: &[u8], flags: c_int) -> io::Result<usize> {

src/sys/windows.rs

@@ -30,7 +30,7 @@ use winapi::um::processthreadsapi::GetCurrentProcessId;
 use winapi::um::winbase::INFINITE;
 use winapi::um::winsock2 as sock;
 
-use crate::SockAddr;
+use crate::{RecvFlags, SockAddr};
 
 const HANDLE_FLAG_INHERIT: DWORD = 0x00000001;
 const MSG_PEEK: c_int = 0x2;
@@ -42,6 +42,9 @@ const WSA_FLAG_OVERLAPPED: DWORD = 0x01;
 
 pub use winapi::ctypes::c_int;
 
+/// Fake MSG_TRUNC flag for the [`RecvFlags`] struct.
+pub(crate) const MSG_TRUNC: c_int = sock::WSAEMSGSIZE;
+
 // Used in `Domain`.
 pub(crate) use winapi::shared::ws2def::{AF_INET, AF_INET6};
 // Used in `Type`.
@@ -342,7 +345,7 @@ impl Socket {
         &self,
         bufs: &mut [IoSliceMut<'_>],
         flags: c_int,
-    ) -> io::Result<(usize, bool)> {
+    ) -> io::Result<(usize, RecvFlags)> {
         let mut nread = 0;
         let mut flags = flags as DWORD;
         let ret = unsafe {
@@ -359,12 +362,12 @@ impl Socket {
 
         let nread = nread as usize;
         if ret == 0 {
-            Ok((nread, false))
+            Ok((nread, RecvFlags(0)))
         } else {
             let error = last_error();
             match error.raw_os_error() {
-                Some(sock::WSAESHUTDOWN) => Ok((0, false)),
-                Some(sock::WSAEMSGSIZE) => Ok((nread, true)),
+                Some(sock::WSAESHUTDOWN) => Ok((0, RecvFlags(0))),
+                Some(sock::WSAEMSGSIZE) => Ok((nread, RecvFlags(MSG_TRUNC))),
                 _ => Err(error),
             }
         }
@@ -374,7 +377,7 @@ impl Socket {
         &self,
         bufs: &mut [IoSliceMut<'_>],
         flags: c_int,
-    ) -> io::Result<(usize, bool, SockAddr)> {
+    ) -> io::Result<(usize, RecvFlags, SockAddr)> {
         let mut nread = 0;
         let mut flags = flags as DWORD;
         let mut storage: SOCKADDR_STORAGE = unsafe { mem::zeroed() };
@@ -393,20 +396,20 @@ impl Socket {
             )
         };
 
-        let truncated;
+        let flags;
         if ret == 0 {
-            truncated = false;
+            flags = RecvFlags(0);
         } else {
             let error = last_error();
             if error.raw_os_error() == Some(sock::WSAEMSGSIZE) {
-                truncated = true;
+                flags = RecvFlags(MSG_TRUNC)
             } else {
                 return Err(error);
             }
         }
 
         let addr = unsafe { SockAddr::from_raw_parts(&storage as *const _ as *const _, addrlen) };
-        Ok((nread as usize, truncated, addr))
+        Ok((nread as usize, flags, addr))
     }
 
     pub fn send(&self, buf: &[u8], flags: c_int) -> io::Result<usize> {

src/tests.rs

@@ -176,7 +176,7 @@ fn send_recv_vectored() {
     let mut yell = [0u8; 4];
     let mut ow = [0u8; 2];
 
-    let (received, truncated) = socket_b
+    let (received, flags) = socket_b
         .recv_vectored(
             &mut [
                 IoSliceMut::new(&mut the),
@@ -190,7 +190,11 @@ fn send_recv_vectored() {
         )
         .unwrap();
     assert_eq!(received, 23);
-    assert_eq!(truncated, false);
+    #[cfg(all(unix, not(target_os = "redox")))]
+    assert_eq!(flags.is_end_of_record(), false);
+    #[cfg(all(unix, not(target_os = "redox")))]
+    assert_eq!(flags.is_out_of_band(), false);
+    assert_eq!(flags.is_trunctated(), false);
 
     assert_eq!(&the, b"the");
     assert_eq!(&wee, b"wee");
@@ -226,7 +230,7 @@ fn send_from_recv_to_vectored() {
     let mut has = [0u8; 3];
     let mut men = [0u8; 3];
     let mut swear = [0u8; 5];
-    let (received, truncated, addr) = socket_b
+    let (received, flags, addr) = socket_b
         .recv_from_vectored(
             &mut [
                 IoSliceMut::new(&mut surgeon),
@@ -239,7 +243,11 @@ fn send_from_recv_to_vectored() {
         .unwrap();
 
     assert_eq!(received, 18);
-    assert_eq!(truncated, false);
+    #[cfg(all(unix, not(target_os = "redox")))]
+    assert_eq!(flags.is_end_of_record(), false);
+    #[cfg(all(unix, not(target_os = "redox")))]
+    assert_eq!(flags.is_out_of_band(), false);
+    assert_eq!(flags.is_trunctated(), false);
     assert_eq!(addr.as_inet6().unwrap(), addr_a.as_inet6().unwrap());
     assert_eq!(&surgeon, b"surgeon");
     assert_eq!(&has, b"has");
@@ -261,11 +269,11 @@ fn recv_vectored_truncated() {
 
     let mut buffer = [0u8; 24];
 
-    let (received, truncated) = socket_b
+    let (received, flags) = socket_b
         .recv_vectored(&mut [IoSliceMut::new(&mut buffer)], 0)
         .unwrap();
     assert_eq!(received, 24);
-    assert_eq!(truncated, true);
+    assert_eq!(flags.is_trunctated(), true);
     assert_eq!(&buffer, b"do not feed the gremlins");
 }
 
@@ -285,11 +293,11 @@ fn recv_from_vectored_truncated() {
 
     let mut buffer = [0u8; 24];
 
-    let (received, truncated, addr) = socket_b
+    let (received, flags, addr) = socket_b
         .recv_from_vectored(&mut [IoSliceMut::new(&mut buffer)], 0)
         .unwrap();
     assert_eq!(received, 24);
-    assert_eq!(truncated, true);
+    assert_eq!(flags.is_trunctated(), true);
     assert_eq!(addr.as_inet6().unwrap(), addr_a.as_inet6().unwrap());
     assert_eq!(&buffer, b"do not feed the gremlins");
 }