Add support for SO_TXTIME / SCM_TXTIME

This is an undocumented linux feature that lets you time outgoing
packets.

Author: colinmarc

src/backend/libc/net/sockopt.rs

@@ -49,9 +49,13 @@ use crate::net::Protocol;
 use crate::net::RawProtocol;
 #[cfg(any(linux_kernel, target_os = "fuchsia"))]
 use crate::net::SocketAddrV4;
+#[cfg(all(target_os = "linux", feature = "time"))]
+use crate::net::TxTimeFlags;
 use crate::net::{Ipv4Addr, Ipv6Addr, SocketType};
 #[cfg(linux_kernel)]
 use crate::net::{SocketAddrV6, UCred};
+#[cfg(all(target_os = "linux", feature = "time"))]
+use crate::time::ClockId;
 use crate::utils::as_mut_ptr;
 #[cfg(feature = "alloc")]
 #[cfg(any(
@@ -1046,6 +1050,35 @@ pub(crate) fn socket_peercred(fd: BorrowedFd<'_>) -> io::Result<UCred> {
     getsockopt(fd, c::SOL_SOCKET, c::SO_PEERCRED)
 }
 
+#[cfg(all(target_os = "linux", feature = "time"))]
+#[inline]
+pub(crate) fn set_txtime(
+    fd: BorrowedFd<'_>,
+    clockid: ClockId,
+    flags: TxTimeFlags,
+) -> io::Result<()> {
+    setsockopt(
+        fd,
+        c::SOL_SOCKET,
+        c::SO_TXTIME,
+        c::sock_txtime {
+            clockid: clockid as _,
+            flags: flags.bits(),
+        },
+    )
+}
+
+#[cfg(all(target_os = "linux", feature = "time"))]
+#[inline]
+pub(crate) fn get_txtime(fd: BorrowedFd<'_>) -> io::Result<(ClockId, TxTimeFlags)> {
+    let txtime: c::sock_txtime = getsockopt(fd, c::SOL_SOCKET, c::SO_TXTIME)?;
+
+    Ok((
+        txtime.clockid.try_into().map_err(|_| io::Errno::RANGE)?,
+        TxTimeFlags::from_bits(txtime.flags).ok_or(io::Errno::RANGE)?,
+    ))
+}
+
 #[cfg(target_os = "linux")]
 #[inline]
 pub(crate) fn set_xdp_umem_reg(fd: BorrowedFd<'_>, value: XdpUmemReg) -> io::Result<()> {

src/backend/linux_raw/c.rs

@@ -97,9 +97,9 @@ pub(crate) use linux_raw_sys::{
         SO_DOMAIN, SO_ERROR, SO_INCOMING_CPU, SO_KEEPALIVE, SO_LINGER, SO_OOBINLINE,
         SO_ORIGINAL_DST, SO_PASSCRED, SO_PROTOCOL, SO_RCVBUF, SO_RCVBUFFORCE, SO_RCVTIMEO_NEW,
         SO_RCVTIMEO_NEW as SO_RCVTIMEO, SO_RCVTIMEO_OLD, SO_REUSEADDR, SO_REUSEPORT, SO_SNDBUF,
-        SO_SNDBUFFORCE, SO_SNDTIMEO_NEW, SO_SNDTIMEO_NEW as SO_SNDTIMEO, SO_SNDTIMEO_OLD, SO_TYPE,
-        TCP_CONGESTION, TCP_CORK, TCP_KEEPCNT, TCP_KEEPIDLE, TCP_KEEPINTVL, TCP_NODELAY,
-        TCP_QUICKACK, TCP_THIN_LINEAR_TIMEOUTS, TCP_USER_TIMEOUT,
+        SO_SNDBUFFORCE, SO_SNDTIMEO_NEW, SO_SNDTIMEO_NEW as SO_SNDTIMEO, SO_SNDTIMEO_OLD,
+        SO_TXTIME, SO_TYPE, TCP_CONGESTION, TCP_CORK, TCP_KEEPCNT, TCP_KEEPIDLE, TCP_KEEPINTVL,
+        TCP_NODELAY, TCP_QUICKACK, TCP_THIN_LINEAR_TIMEOUTS, TCP_USER_TIMEOUT,
     },
     netlink::*,
     xdp::{
@@ -114,6 +114,19 @@ pub(crate) use linux_raw_sys::{
     },
 };
 
+// TODO:  https://github.com/sunfishcode/linux-raw-sys/pull/153
+#[cfg(all(feature = "net", feature = "time"))]
+pub(crate) const SOF_TXTIME_DEADLINE_MODE: u32 = 0x1;
+#[cfg(all(feature = "net", feature = "time"))]
+pub(crate) const SOF_TXTIME_REPORT_ERRORS: u32 = 0x2;
+#[cfg(all(feature = "net", feature = "time"))]
+#[repr(C)]
+#[derive(Debug, Copy, Clone)]
+pub(crate) struct sock_txtime {
+    pub(crate) clockid: __kernel_clockid_t,
+    pub(crate) flags: u32,
+}
+
 // Cast away bindgen's `enum` type to make these consistent with the other
 // `setsockopt`/`getsockopt` level values.
 #[cfg(feature = "net")]

src/backend/linux_raw/net/sockopt.rs

@@ -7,13 +7,17 @@
 
 use crate::backend::c;
 use crate::backend::conv::{by_mut, c_uint, ret, socklen_t};
+#[cfg(all(target_os = "linux", feature = "time"))]
+use crate::clockid::ClockId;
 use crate::fd::BorrowedFd;
 #[cfg(feature = "alloc")]
 use crate::ffi::CStr;
 use crate::io;
 use crate::net::sockopt::Timeout;
 #[cfg(target_os = "linux")]
 use crate::net::xdp::{XdpMmapOffsets, XdpOptionsFlags, XdpRingOffset, XdpStatistics, XdpUmemReg};
+#[cfg(all(target_os = "linux", feature = "time"))]
+use crate::net::TxTimeFlags;
 use crate::net::{
     AddressFamily, Ipv4Addr, Ipv6Addr, Protocol, RawProtocol, SocketAddrBuf, SocketAddrV4,
     SocketAddrV6, SocketType, UCred,
@@ -848,6 +852,35 @@ pub(crate) fn socket_peercred(fd: BorrowedFd<'_>) -> io::Result<UCred> {
     getsockopt(fd, c::SOL_SOCKET, linux_raw_sys::net::SO_PEERCRED)
 }
 
+#[cfg(all(target_os = "linux", feature = "time"))]
+#[inline]
+pub(crate) fn set_txtime(
+    fd: BorrowedFd<'_>,
+    clockid: ClockId,
+    flags: TxTimeFlags,
+) -> io::Result<()> {
+    setsockopt(
+        fd,
+        c::SOL_SOCKET,
+        c::SO_TXTIME,
+        c::sock_txtime {
+            clockid: clockid as _,
+            flags: flags.bits(),
+        },
+    )
+}
+
+#[cfg(all(target_os = "linux", feature = "time"))]
+#[inline]
+pub(crate) fn get_txtime(fd: BorrowedFd<'_>) -> io::Result<(ClockId, TxTimeFlags)> {
+    let txtime: c::sock_txtime = getsockopt(fd, c::SOL_SOCKET, c::SO_TXTIME)?;
+
+    Ok((
+        txtime.clockid.try_into().map_err(|_| io::Errno::RANGE)?,
+        TxTimeFlags::from_bits(txtime.flags).ok_or(io::Errno::RANGE)?,
+    ))
+}
+
 #[cfg(target_os = "linux")]
 #[inline]
 pub(crate) fn set_xdp_umem_reg(fd: BorrowedFd<'_>, value: XdpUmemReg) -> io::Result<()> {

src/clockid.rs

@@ -1,5 +1,6 @@
 use crate::backend::c;
 use crate::fd::BorrowedFd;
+use crate::io;
 
 /// `CLOCK_*` constants for use with [`clock_gettime`].
 ///
@@ -94,6 +95,51 @@ pub enum ClockId {
     BoottimeAlarm = bitcast!(c::CLOCK_BOOTTIME_ALARM),
 }
 
+#[cfg(not(any(apple, target_os = "wasi")))]
+impl TryFrom<c::clockid_t> for ClockId {
+    type Error = io::Errno;
+
+    fn try_from(value: c::clockid_t) -> Result<Self, Self::Error> {
+        match value {
+            c::CLOCK_REALTIME => Ok(ClockId::Realtime),
+            c::CLOCK_MONOTONIC => Ok(ClockId::Monotonic),
+            #[cfg(any(freebsdlike, target_os = "openbsd"))]
+            c::CLOCK_UPTIME => Ok(ClockId::Uptime),
+            #[cfg(not(any(
+                solarish,
+                target_os = "horizon",
+                target_os = "netbsd",
+                target_os = "redox",
+                target_os = "vita"
+            )))]
+            c::CLOCK_PROCESS_CPUTIME_ID => Ok(ClockId::ProcessCPUTime),
+            #[cfg(not(any(
+                solarish,
+                target_os = "horizon",
+                target_os = "netbsd",
+                target_os = "redox",
+                target_os = "vita"
+            )))]
+            c::CLOCK_THREAD_CPUTIME_ID => Ok(ClockId::ThreadCPUTime),
+            #[cfg(any(linux_kernel, target_os = "freebsd"))]
+            c::CLOCK_REALTIME_COARSE => Ok(ClockId::RealtimeCoarse),
+            #[cfg(any(linux_kernel, target_os = "freebsd"))]
+            c::CLOCK_MONOTONIC_COARSE => Ok(ClockId::MonotonicCoarse),
+            #[cfg(linux_kernel)]
+            c::CLOCK_MONOTONIC_RAW => Ok(ClockId::MonotonicRaw),
+            #[cfg(linux_kernel)]
+            c::CLOCK_REALTIME_ALARM => Ok(ClockId::RealtimeAlarm),
+            #[cfg(all(linux_kernel, feature = "linux_4_11"))]
+            c::CLOCK_TAI => Ok(ClockId::Tai),
+            #[cfg(any(linux_kernel, target_os = "fuchsia", target_os = "openbsd"))]
+            c::CLOCK_BOOTTIME => Ok(ClockId::Boottime),
+            #[cfg(any(linux_kernel, target_os = "fuchsia"))]
+            c::CLOCK_BOOTTIME_ALARM => Ok(ClockId::BoottimeAlarm),
+            _ => Err(io::Errno::RANGE),
+        }
+    }
+}
+
 /// `CLOCK_*` constants for use with [`clock_gettime`].
 ///
 /// These constants are always supported at runtime, so `clock_gettime` never
@@ -124,6 +170,21 @@ pub enum ClockId {
     ThreadCPUTime = c::CLOCK_THREAD_CPUTIME_ID,
 }
 
+#[cfg(apple)]
+impl TryFrom<c::clockid_t> for ClockId {
+    type Error = io::Errno;
+
+    fn try_from(value: c::clockid_t) -> Result<Self, Self::Error> {
+        match value {
+            c::CLOCK_REALTIME => Ok(ClockId::Realtime),
+            c::CLOCK_MONOTONIC => Ok(ClockId::Monotonic),
+            c::CLOCK_PROCESS_CPUTIME_ID => Ok(ClockId::ProcessCPUTime),
+            c::CLOCK_THREAD_CPUTIME_ID => Ok(ClockId::ThreadCPUTime),
+            _ => Err(io::Errno::RANGE),
+        }
+    }
+}
+
 /// `CLOCK_*` constants for use with [`clock_gettime_dynamic`].
 ///
 /// These constants may be unsupported at runtime, depending on the OS version,

src/net/send_recv/msg.rs

@@ -66,6 +66,11 @@ macro_rules! cmsg_space {
             $len * ::core::mem::size_of::<$crate::net::UCred>(),
         )
     };
+    (TxTime($len:expr)) => {
+        $crate::net::__cmsg_space(
+            $len * ::core::mem::size_of::<u64>(),
+        )
+    };
 
     // Combo Rules
     ($firstid:ident($firstex:expr), $($restid:ident($restex:expr)),*) => {{
@@ -94,6 +99,11 @@ macro_rules! cmsg_aligned_space {
             $len * ::core::mem::size_of::<$crate::net::UCred>(),
         )
     };
+    (TxTime($len:expr)) => {
+        $crate::net::__cmsg_aligned_space(
+            $len * ::core::mem::size_of::<u64>(),
+        )
+    };
 
     // Combo Rules
     ($firstid:ident($firstex:expr), $($restid:ident($restex:expr)),*) => {{
@@ -138,6 +148,13 @@ pub enum SendAncillaryMessage<'slice, 'fd> {
     #[cfg(linux_kernel)]
     #[doc(alias = "SCM_CREDENTIAL")]
     ScmCredentials(UCred),
+    /// Transmission time, in nanoseconds. The value will be interpreted by
+    /// whichever clock was configured on the socket with [set_txtime].
+    ///
+    /// [set_txtime]: (super::sockopt::set_txtime).
+    #[cfg(target_os = "linux")]
+    #[doc(alias = "SCM_TXTIME")]
+    TxTime(u64),
 }
 
 impl SendAncillaryMessage<'_, '_> {
@@ -149,6 +166,8 @@ impl SendAncillaryMessage<'_, '_> {
             Self::ScmRights(slice) => cmsg_space!(ScmRights(slice.len())),
             #[cfg(linux_kernel)]
             Self::ScmCredentials(_) => cmsg_space!(ScmCredentials(1)),
+            #[cfg(target_os = "linux")]
+            Self::TxTime(_) => cmsg_space!(TxTime(1)),
         }
     }
 }
@@ -290,6 +309,13 @@ impl<'buf, 'slice, 'fd> SendAncillaryBuffer<'buf, 'slice, 'fd> {
                 };
                 self.push_ancillary(ucred_bytes, c::SOL_SOCKET as _, c::SCM_CREDENTIALS as _)
             }
+            #[cfg(target_os = "linux")]
+            SendAncillaryMessage::TxTime(tx_time) => {
+                let tx_time_bytes = unsafe {
+                    slice::from_raw_parts(addr_of!(tx_time).cast::<u8>(), size_of_val(&tx_time))
+                };
+                self.push_ancillary(tx_time_bytes, c::SOL_SOCKET as _, c::SO_TXTIME as _)
+            }
         }
     }
 

src/net/sockopt.rs

@@ -143,6 +143,8 @@
 #![doc(alias = "getsockopt")]
 #![doc(alias = "setsockopt")]
 
+#[cfg(all(target_os = "linux", feature = "time"))]
+use crate::clockid::ClockId;
 #[cfg(target_os = "linux")]
 use crate::net::xdp::{XdpMmapOffsets, XdpOptionsFlags, XdpStatistics, XdpUmemReg};
 #[cfg(not(any(
@@ -171,6 +173,8 @@ use crate::net::Protocol;
 use crate::net::SocketAddrV4;
 #[cfg(linux_kernel)]
 use crate::net::SocketAddrV6;
+#[cfg(all(target_os = "linux", feature = "time"))]
+use crate::net::TxTimeFlags;
 use crate::net::{Ipv4Addr, Ipv6Addr, SocketType};
 use crate::{backend, io};
 #[cfg(feature = "alloc")]
@@ -1522,6 +1526,20 @@ pub fn socket_peercred<Fd: AsFd>(fd: Fd) -> io::Result<super::UCred> {
     backend::net::sockopt::socket_peercred(fd.as_fd())
 }
 
+/// `getsockopt(fd, SOL_SOCKET, SO_TXTIME)` — Get transmission timing configuration.
+#[cfg(all(target_os = "linux", feature = "time"))]
+#[doc(alias = "SO_TXTIME")]
+pub fn get_txtime<Fd: AsFd>(fd: Fd) -> io::Result<(ClockId, TxTimeFlags)> {
+    backend::net::sockopt::get_txtime(fd.as_fd())
+}
+
+/// `setsockopt(fd, SOL_SOCKET, SO_TXTIME)` — Configure transmission timing.
+#[cfg(all(target_os = "linux", feature = "time"))]
+#[doc(alias = "SO_TXTIME")]
+pub fn set_txtime<Fd: AsFd>(fd: Fd, clockid: ClockId, flags: TxTimeFlags) -> io::Result<()> {
+    backend::net::sockopt::set_txtime(fd.as_fd(), clockid, flags)
+}
+
 /// `setsockopt(fd, SOL_XDP, XDP_UMEM_REG, value)`
 ///
 /// On kernel versions only supporting v1, the flags are ignored.

src/net/types.rs

@@ -1680,6 +1680,22 @@ bitflags! {
     }
 }
 
+#[cfg(all(target_os = "linux", feature = "time"))]
+bitflags! {
+    /// Flags for use with [`set_txtime`].
+    ///
+    /// [`set_txtime`]: crate::net::sockopt::set_txtime
+    /// [`get_txtime`]: crate::net::sockopt::get_txtime
+    #[repr(transparent)]
+    #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
+    pub struct TxTimeFlags: u32 {
+        /// `SOF_TXTIME_DEADLINE_MODE`
+        const DEADLINE_MODE = bitcast!(c::SOF_TXTIME_DEADLINE_MODE);
+        /// `SOF_TXTIME_REPORT_ERRORS`
+        const REPORT_ERRORS = bitcast!(c::SOF_TXTIME_REPORT_ERRORS);
+    }
+}
+
 /// `AF_XDP` related types and constants.
 #[cfg(target_os = "linux")]
 pub mod xdp {

tests/net/sockopt.rs

@@ -9,7 +9,11 @@ use rustix::io;
     target_env = "newlib"
 ))]
 use rustix::net::ipproto;
+#[cfg(target_os = "linux")]
+use rustix::net::TxTimeFlags;
 use rustix::net::{sockopt, AddressFamily, SocketType};
+#[cfg(target_os = "linux")]
+use rustix::time::ClockId;
 use std::net::Ipv4Addr;
 use std::time::Duration;
 
@@ -188,6 +192,20 @@ fn test_sockopts_socket(s: &OwnedFd) {
         sockopt::set_socket_nosigpipe(s, true).unwrap();
         assert_eq!(sockopt::socket_nosigpipe(s).unwrap(), true);
     }
+
+    // Check the initial value of `SO_TXTIME`, set it, and check it.
+    #[cfg(target_os = "linux")]
+    {
+        assert_eq!(
+            sockopt::get_txtime(s).unwrap(),
+            (ClockId::Realtime, TxTimeFlags::empty())
+        );
+        sockopt::set_txtime(s, ClockId::Monotonic, TxTimeFlags::DEADLINE_MODE).unwrap();
+        assert_eq!(
+            sockopt::get_txtime(s).unwrap(),
+            (ClockId::Monotonic, TxTimeFlags::DEADLINE_MODE)
+        );
+    }
 }
 
 // Test `tcp` socket options.