Tracking Issue for #138744: Add methods to TCP and UDP sockets to modify IPv6 hop limits

Feature gate: #![feature(ipv6_hop_limit)]

This is a tracking issue for adding methods to set the values for IPV6_UNICAST_HOPS and IPV6_MULTICAST_HOPS on TCP and UDP ipv6 sockets.

Public API

TCP sockets

impl TcpStream {
  /// #![feature(ipv6_hop_limit)]
  /// use std::net::TcpStream;
  ///
  /// let stream = TcpStream::connect("[::1]:12345")
  ///                        .expect("Couldn't connect to the server...");
  /// stream.set_hop_limit_v6(88).expect("set_hop_limit_v6 call failed");
  /// ```
  pub fn set_hop_limit_v6(&self, limit: u8) -> io::Result<()>;

  /// Gets the value of the `IPV6_UNICAST_HOPS` option on this socket.
  ///
  /// For more information about this option, see [`TcpStream::set_hop_limit_v6`].
  ///
  /// # Examples
  ///
  /// ```no_run
  /// #![feature(ipv6_hop_limit)]
  /// use std::net::TcpStream;
  ///
  /// let stream = TcpStream::connect("[::1]:12345")
  ///                        .expect("Couldn't connect to the server...");
  /// stream.set_hop_limit_v6(88).expect("set_hop_limit_v6 call failed");
  /// assert_eq!(stream.hop_limit_v6().unwrap(), 88);
  /// ```
  pub fn hop_limit_v6(&self) -> io::Result<u8>;
}

impl TcpListener {
  /// Sets the value for the `IPV6_UNICAST_HOPS` option on this socket.
  ///
  /// This value sets the unicast hop limit field that is used in every packet
  /// sent from this socket.
  ///
  /// # Examples
  ///
  /// ```no_run
  /// #![feature(ipv6_hop_limit)]
  /// use std::net::TcpListener;
  ///
  /// let listener = TcpListener::bind("[::1]:12345").unwrap();
  /// listener.set_hop_limit_v6(88).expect("set_hop_limit_v6 call failed");
  /// ```
  pub fn set_hop_limit_v6(&self, limit: u8) -> io::Result<()>;

  /// Gets the value of the `IPV6_UNICAST_HOPS` option on this socket.
  ///
  /// For more information about this option, see [`TcpListener::set_hop_limit_v6`].
  ///
  /// # Examples
  ///
  /// ```no_run
  /// #![feature(ipv6_hop_limit)]
  /// use std::net::TcpListener;
  ///
  /// let listener = TcpListener::bind("[::1]:12345").unwrap();
  /// listener.set_hop_limit_v6(88).expect("set_hop_limit_v6 call failed");
  /// assert_eq!(listener.hop_limit_v6().unwrap(), 88);
  /// ```
  pub fn hop_limit_v6(&self) -> io::Result<u8>;
}

UDP sockets

impl UdpSocket {
  /// Sets the value for the `IPV6_UNICAST_HOPS` option on this socket.
  ///
  /// This value sets the unicast hop limit field that is used in every packet
  /// sent from this socket.
  ///
  /// # Examples
  ///
  /// ```no_run
  /// #![feature(ipv6_hop_limit)]
  /// use std::net::UdpSocket;
  ///
  /// let socket = UdpSocket::bind("[::1]:12345").expect("couldn't bind to address");
  /// socket.set_hop_limit_v6(88).expect("set_hop_limit_v6 call failed");
  /// ```
  pub fn set_hop_limit_v6(&self, limit: u8) -> io::Result<()>;

  /// Gets the value of the `IPV6_UNICAST_HOPS` option on this socket.
  ///
  /// For more information about this option, see [`UdpSocket::set_hop_limit_v6`].
  ///
  /// # Examples
  ///
  /// ```no_run
  /// #![feature(ipv6_hop_limit)]
  /// use std::net::UdpSocket;
  ///
  /// let socket = UdpSocket::bind("[::1]:12345").expect("couldn't bind to address");
  /// socket.set_hop_limit_v6(88).expect("set_hop_limit_v6 call failed");
  /// assert_eq!(socket.hop_limit_v6().unwrap(), 88);
  /// ```
  pub fn hop_limit_v6(&self) -> io::Result<u8>;

  /// Sets the value for the `IPV6_MULTICAST_HOPS` option on this socket.
  ///
  /// This value sets the hop limit field for outgoing multicast packets sent from this socket.
  ///
  /// # Examples
  ///
  /// ```no_run
  /// #![feature(ipv6_hop_limit)]
  /// use std::net::UdpSocket;
  ///
  /// let socket = UdpSocket::bind("[::1]:12345").expect("couldn't bind to address");
  /// socket.set_multicast_hop_limit_v6(88).expect("set_multicast_hop_limit_v6 call failed");
  /// ```
  pub fn set_multicast_hop_limit_v6(&self, limit: u8) -> io::Result<()>;

  /// Gets the value of the `IPV6_MULTICAST_HOPS` option on this socket.
  ///
  /// # Examples
  ///
  /// ```no_run
  /// #![feature(ipv6_hop_limit)]
  /// use std::net::UdpSocket;
  ///
  /// let socket = UdpSocket::bind("[::1]:12345").expect("couldn't bind to address");
  /// socket.set_multicast_hop_limit_v6(88).expect("set_multicast_hop_limit_v6 call failed");
  /// assert_eq!(socket.multicast_hop_limit_v6().unwrap(), 88);
  /// ```
  pub fn multicast_hop_limit_v6(&self) -> io::Result<u8>;
}

Steps

• Implementation:
  • unstable https://github.com/rust-lang/rust/pull/138744
• Final comment period (FCP)^1
• Stabilization PR

History

• Original issue https://github.com/rust-lang/rust/issues/47727
• First (abandoned) implementation https://github.com/rust-lang/rust/pull/94678

Unresolved Questions

• None yet.

Start with the implementation linked in pull request #138744 and compare it with the proposed TCP, TcpListener, and UdpSocket APIs in this issue. The tracking work is complete when implementation, the final comment period, and stabilization have all been addressed.