diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index 2eabb46441b..5467eff202b 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -111,15 +111,18 @@ impl TcpStream { /// `addr` is an address of the remote host. Anything which implements /// [`ToSocketAddrs`] trait can be supplied for the address; see this trait /// documentation for concrete examples. - /// In case [`ToSocketAddrs::to_socket_addrs()`] returns more than one entry, - /// then the first valid and reachable address is used. + /// + /// If `addr` yields multiple addresses, `connect` will be attempted with + /// each of the addresses until a connection is successful. If none of + /// the addresses result in a successful connection, the error returned from + /// the last connection attempt (the last address) is returned. /// /// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html - /// [`ToSocketAddrs::to_socket_addrs()`]: - /// ../../std/net/trait.ToSocketAddrs.html#tymethod.to_socket_addrs /// /// # Examples /// + /// Open a TCP connection to `127.0.0.1:8080`: + /// /// ```no_run /// use std::net::TcpStream; /// @@ -129,6 +132,23 @@ impl TcpStream { /// println!("Couldn't connect to server..."); /// } /// ``` + /// + /// Open a TCP connection to `127.0.0.1:8080`. If the connection fails, open + /// a TCP connection to `127.0.0.1:8081`: + /// + /// ```no_run + /// use std::net::{SocketAddr, TcpStream}; + /// + /// let addrs = [ + /// SocketAddr::from(([127, 0, 0, 1], 8080)), + /// SocketAddr::from(([127, 0, 0, 1], 8081)), + /// ]; + /// if let Ok(stream) = TcpStream::connect(&addrs[..]) { + /// println!("Connected to the server!"); + /// } else { + /// println!("Couldn't connect to server..."); + /// } + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn connect(addr: A) -> io::Result { super::each_addr(addr, net_imp::TcpStream::connect).map(TcpStream) @@ -557,16 +577,36 @@ impl TcpListener { /// The address type can be any implementor of [`ToSocketAddrs`] trait. See /// its documentation for concrete examples. /// + /// If `addr` yields multiple addresses, `bind` will be attempted with + /// each of the addresses until one succeeds and returns the listener. If + /// none of the addresses succeed in creating a listener, the error returned + /// from the last attempt (the last address) is returned. + /// /// [`local_addr`]: #method.local_addr /// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html /// /// # Examples /// + /// Create a TCP listener bound to `127.0.0.1:80`: + /// /// ```no_run /// use std::net::TcpListener; /// /// let listener = TcpListener::bind("127.0.0.1:80").unwrap(); /// ``` + /// + /// Create a TCP listener bound to `127.0.0.1:80`. If that fails, create a + /// TCP listener bound to `127.0.0.1:443`: + /// + /// ```no_run + /// use std::net::{SocketAddr, TcpListener}; + /// + /// let addrs = [ + /// SocketAddr::from(([127, 0, 0, 1], 80)), + /// SocketAddr::from(([127, 0, 0, 1], 443)), + /// ]; + /// let listener = TcpListener::bind(&addrs[..]).unwrap(); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn bind(addr: A) -> io::Result { super::each_addr(addr, net_imp::TcpListener::bind).map(TcpListener) diff --git a/src/libstd/net/udp.rs b/src/libstd/net/udp.rs index 9aff9897885..35001833383 100644 --- a/src/libstd/net/udp.rs +++ b/src/libstd/net/udp.rs @@ -69,14 +69,34 @@ impl UdpSocket { /// The address type can be any implementor of [`ToSocketAddrs`] trait. See /// its documentation for concrete examples. /// + /// If `addr` yields multiple addresses, `bind` will be attempted with + /// each of the addresses until one succeeds and returns the socket. If none + /// of the addresses succeed in creating a socket, the error returned from + /// the last attempt (the last address) is returned. + /// /// [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html /// /// # Examples /// + /// Create a UDP socket bound to `127.0.0.1:3400`: + /// /// ```no_run /// use std::net::UdpSocket; /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); + /// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address"); + /// ``` + /// + /// Create a UDP socket bound to `127.0.0.1:3400`. If the socket cannot be + /// bound to that address, create a UDP socket bound to `127.0.0.1:3401`: + /// + /// ```no_run + /// use std::net::{SocketAddr, UdpSocket}; + /// + /// let addrs = [ + /// SocketAddr::from(([127, 0, 0, 1], 3400)), + /// SocketAddr::from(([127, 0, 0, 1], 3401)), + /// ]; + /// let socket = UdpSocket::bind(&addrs[..]).expect("couldn't bind to address"); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn bind(addr: A) -> io::Result { @@ -130,6 +150,9 @@ pub fn peek_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { /// Address type can be any implementor of [`ToSocketAddrs`] trait. See its /// documentation for concrete examples. /// + /// It is possible for `addr` to yield multiple addresses, but `send_to` + /// will only send data to the first address yielded by `addr`. + /// /// This will return an error when the IP version of the local socket /// does not match that returned from [`ToSocketAddrs`]. /// @@ -562,14 +585,37 @@ pub fn take_error(&self) -> io::Result> { /// `recv` syscalls to be used to send data and also applies filters to only /// receive data from the specified address. /// + /// If `addr` yields multiple addresses, `connect` will be attempted with + /// each of the addresses until a connection is successful. If none of + /// the addresses are able to be connected, the error returned from the + /// last connection attempt (the last address) is returned. + /// /// # Examples /// + /// Create a UDP socket bound to `127.0.0.1:3400` and connect the socket to + /// `127.0.0.1:8080`: + /// /// ```no_run /// use std::net::UdpSocket; /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); + /// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address"); /// socket.connect("127.0.0.1:8080").expect("connect function failed"); /// ``` + /// + /// Create a UDP socket bound to `127.0.0.1:3400` and connect the socket to + /// `127.0.0.1:8080`. If that connection fails, then the UDP socket will + /// connect to `127.0.0.1:8081`: + /// + /// ```no_run + /// use std::net::{SocketAddr, UdpSocket}; + /// + /// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address"); + /// let connect_addrs = [ + /// SocketAddr::from(([127, 0, 0, 1], 8080)), + /// SocketAddr::from(([127, 0, 0, 1], 8081)), + /// ]; + /// socket.connect(&connect_addrs[..]).expect("connect function failed"); + /// ``` #[stable(feature = "net2_mutators", since = "1.9.0")] pub fn connect(&self, addr: A) -> io::Result<()> { super::each_addr(addr, |addr| self.0.connect(addr))