Skip to content

Commit adb22b9

Browse files
Improve UdpSocket documentation
I tried working with `UdpSocket` and ran into `EINVAL` errors with no clear indication of what causes the error. Also, it was uncharacteristically hard to figure this module out, compared to other Rust `std` modules. 1. `send` and `send_to` return a `usize` This one is just clarity. Usually, returned `usize`s indicate that the buffer might have only been sent partially. This is not the case with UDP. Since that `usize` must always be `buffer.len()`, I have documented that. 2. `bind` limits `connect` and `send_to` When you bind to a limited address space like localhost, you can only `connect` to addresses in that same address space. Error kind: `AddrNotAvailable`. 3. `connect`ing to localhost locks you to localhost On Linux, if you first `connect` to localhost, subsequent `connect`s to non-localhost addresses fail. Error kind: `InvalidInput`. Co-authored-by: Jubilee <[email protected]>
1 parent 320b412 commit adb22b9

File tree

1 file changed

+20
-1
lines changed

1 file changed

+20
-1
lines changed

library/std/src/net/udp.rs

+20-1
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,16 @@ impl UdpSocket {
9999
///
100100
/// let socket = UdpSocket::bind("127.0.0.1:0").unwrap();
101101
/// ```
102+
///
103+
/// Note that `bind` declares the scope of your network connection.
104+
/// You can only receive datagrams from and send datagrams to
105+
/// participants in that view of the network.
106+
/// For instance, binding to a loopback address as in the example
107+
/// above will prevent you from sending datagrams to another device
108+
/// in your local network.
109+
///
110+
/// In order to limit your view of the network the least, `bind` to
111+
/// [`Ipv4Addr::UNSPECIFIED`] or [`Ipv6Addr::UNSPECIFIED`].
102112
#[stable(feature = "rust1", since = "1.0.0")]
103113
pub fn bind<A: ToSocketAddrs>(addr: A) -> io::Result<UdpSocket> {
104114
super::each_addr(addr, net_imp::UdpSocket::bind).map(UdpSocket)
@@ -157,7 +167,9 @@ impl UdpSocket {
157167
}
158168

159169
/// Sends data on the socket to the given address. On success, returns the
160-
/// number of bytes written.
170+
/// number of bytes written. Note that the operating system may refuse
171+
/// buffers larger than 65507. However, partial writes are not possible
172+
/// until buffer sizes above `i32::MAX`.
161173
///
162174
/// Address type can be any implementor of [`ToSocketAddrs`] trait. See its
163175
/// documentation for concrete examples.
@@ -652,12 +664,19 @@ impl UdpSocket {
652664
/// function of a UDP socket is not a useful thing to do: The OS will be
653665
/// unable to determine whether something is listening on the remote
654666
/// address without the application sending data.
667+
///
668+
/// If your first `connect` is to a loopback address, subsequent
669+
/// `connect`s to non-loopback addresses might fail, depending
670+
/// on the platform.
655671
#[stable(feature = "net2_mutators", since = "1.9.0")]
656672
pub fn connect<A: ToSocketAddrs>(&self, addr: A) -> io::Result<()> {
657673
super::each_addr(addr, |addr| self.0.connect(addr))
658674
}
659675

660676
/// Sends data on the socket to the remote address to which it is connected.
677+
/// On success, returns the number of bytes written. Note that the operating
678+
/// system may refuse buffers larger than 65507. However, partial writes are
679+
/// not possible until buffer sizes above `i32::MAX`.
661680
///
662681
/// [`UdpSocket::connect`] will connect this socket to a remote address. This
663682
/// method will fail if the socket is not connected.

0 commit comments

Comments
 (0)