Opens a TCP connection to a remote host.

addr is an address of the remote host. Anything which implementsToSocketAddrs trait can be supplied for the address; see this traitdocumentation for concrete examples.

Ifaddr yields multiple addresses,connect will be attempted witheach of the addresses until a connection is successful. If none ofthe addresses result in a successful connection, the error returned fromthe last connection attempt (the last address) is returned.

§Examples

Open a TCP connection to127.0.0.1:8080:

usestd::net::TcpStream;if letOk(stream) = TcpStream::connect("127.0.0.1:8080") {println!("Connected to the server!");}else{println!("Couldn't connect to server...");}

Open a TCP connection to127.0.0.1:8080. If the connection fails, opena TCP connection to127.0.0.1:8081:

usestd::net::{SocketAddr, TcpStream};letaddrs = [    SocketAddr::from(([127,0,0,1],8080)),    SocketAddr::from(([127,0,0,1],8081)),];if letOk(stream) = TcpStream::connect(&addrs[..]) {println!("Connected to the server!");}else{println!("Couldn't connect to server...");}

Opens a TCP connection to a remote host with a timeout.

Unlikeconnect,connect_timeout takes a singleSocketAddr sincetimeout must be applied to individual addresses.

It is an error to pass a zeroDuration to this function.

Unlike other methods onTcpStream, this does not correspond to asingle system call. It instead callsconnect in nonblocking mode andthen uses an OS-specific mechanism to await the completion of theconnection request.

Returns the socket address of the remote peer of this TCP connection.

§Examples

usestd::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpStream};letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");assert_eq!(stream.peer_addr().unwrap(),           SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127,0,0,1),8080)));

Returns the socket address of the local half of this TCP connection.

§Examples

usestd::net::{IpAddr, Ipv4Addr, TcpStream};letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");assert_eq!(stream.local_addr().unwrap().ip(),           IpAddr::V4(Ipv4Addr::new(127,0,0,1)));

Shuts down the read, write, or both halves of this connection.

This function will cause all pending and future I/O on the specifiedportions to return immediately with an appropriate value (see thedocumentation ofShutdown).

§Platform-specific behavior

Calling this function multiple times may result in different behavior,depending on the operating system. On Linux, the second call willreturnOk(()), but on macOS, it will returnErrorKind::NotConnected.This may change in the future.

§Examples

usestd::net::{Shutdown, TcpStream};letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.shutdown(Shutdown::Both).expect("shutdown call failed");

Creates a new independently owned handle to the underlying socket.

The returnedTcpStream is a reference to the same stream that thisobject references. Both handles will read and write the same stream ofdata, and options set on one stream will be propagated to the otherstream.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");letstream_clone = stream.try_clone().expect("clone failed...");

Sets the read timeout to the timeout specified.

If the value specified isNone, thenread calls will blockindefinitely. AnErr is returned if the zeroDuration ispassed to this method.

§Platform-specific behavior

Platforms may return a different error code whenever a read times out asa result of setting this option. For example Unix typically returns anerror of the kindWouldBlock, but Windows may returnTimedOut.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.set_read_timeout(None).expect("set_read_timeout call failed");

AnErr is returned if the zeroDuration is passed to thismethod:

usestd::io;usestd::net::TcpStream;usestd::time::Duration;letstream = TcpStream::connect("127.0.0.1:8080").unwrap();letresult = stream.set_read_timeout(Some(Duration::new(0,0)));leterr = result.unwrap_err();assert_eq!(err.kind(), io::ErrorKind::InvalidInput)

Sets the write timeout to the timeout specified.

If the value specified isNone, thenwrite calls will blockindefinitely. AnErr is returned if the zeroDuration ispassed to this method.

§Platform-specific behavior

Platforms may return a different error code whenever a write times outas a result of setting this option. For example Unix typically returnsan error of the kindWouldBlock, but Windows may returnTimedOut.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.set_write_timeout(None).expect("set_write_timeout call failed");

AnErr is returned if the zeroDuration is passed to thismethod:

usestd::io;usestd::net::TcpStream;usestd::time::Duration;letstream = TcpStream::connect("127.0.0.1:8080").unwrap();letresult = stream.set_write_timeout(Some(Duration::new(0,0)));leterr = result.unwrap_err();assert_eq!(err.kind(), io::ErrorKind::InvalidInput)

Returns the read timeout of this socket.

If the timeout isNone, thenread calls will block indefinitely.

§Platform-specific behavior

Some platforms do not provide access to the current timeout.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.set_read_timeout(None).expect("set_read_timeout call failed");assert_eq!(stream.read_timeout().unwrap(),None);

Returns the write timeout of this socket.

If the timeout isNone, thenwrite calls will block indefinitely.

§Platform-specific behavior

Some platforms do not provide access to the current timeout.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.set_write_timeout(None).expect("set_write_timeout call failed");assert_eq!(stream.write_timeout().unwrap(),None);

Receives data on the socket from the remote address to which it isconnected, without removing that data from the queue. On success,returns the number of bytes peeked.

Successive calls return the same data. This is accomplished by passingMSG_PEEK as a flag to the underlyingrecv system call.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8000")                       .expect("Couldn't connect to the server...");letmutbuf = [0;10];letlen = stream.peek(&mutbuf).expect("peek failed");

Sets the value of theSO_LINGER option on this socket.

This value controls how the socket is closed when data remainsto be sent. IfSO_LINGER is set, the socket will remain openfor the specified duration as the system attempts to send pending data.Otherwise, the system may close the socket immediately, or wait for adefault timeout.

§Examples

#![feature(tcp_linger)]usestd::net::TcpStream;usestd::time::Duration;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.set_linger(Some(Duration::from_secs(0))).expect("set_linger call failed");

Gets the value of theSO_LINGER option on this socket.

For more information about this option, seeTcpStream::set_linger.

§Examples

#![feature(tcp_linger)]usestd::net::TcpStream;usestd::time::Duration;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.set_linger(Some(Duration::from_secs(0))).expect("set_linger call failed");assert_eq!(stream.linger().unwrap(),Some(Duration::from_secs(0)));

Sets the value of theTCP_NODELAY option on this socket.

If set, this option disables the Nagle algorithm. This means thatsegments are always sent as soon as possible, even if there is only asmall amount of data. When not set, data is buffered until there is asufficient amount to send out, thereby avoiding the frequent sending ofsmall packets.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.set_nodelay(true).expect("set_nodelay call failed");

Gets the value of theTCP_NODELAY option on this socket.

For more information about this option, seeTcpStream::set_nodelay.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.set_nodelay(true).expect("set_nodelay call failed");assert_eq!(stream.nodelay().unwrap_or(false),true);

Sets the value for theIP_TTL option on this socket.

This value sets the time-to-live field that is used in every packet sentfrom this socket.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.set_ttl(100).expect("set_ttl call failed");

Gets the value of theIP_TTL option for this socket.

For more information about this option, seeTcpStream::set_ttl.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.set_ttl(100).expect("set_ttl call failed");assert_eq!(stream.ttl().unwrap_or(0),100);

Gets the value of theSO_ERROR option on this socket.

This will retrieve the stored error in the underlying socket, clearingthe field in the process. This can be useful for checking errors betweencalls.

§Examples

usestd::net::TcpStream;letstream = TcpStream::connect("127.0.0.1:8080")                       .expect("Couldn't connect to the server...");stream.take_error().expect("No error was expected...");

Moves this TCP stream into or out of nonblocking mode.

This will result inread,write,recv andsend system operationsbecoming nonblocking, i.e., immediately returning from their calls.If the IO operation is successful,Ok is returned and no furtheraction is required. If the IO operation could not be completed and needsto be retried, an error with kindio::ErrorKind::WouldBlock isreturned.

On Unix platforms, calling this method corresponds to callingfcntlFIONBIO. On Windows calling this method corresponds to callingioctlsocketFIONBIO.

§Examples

Reading bytes from a TCP stream in non-blocking mode:

usestd::io::{self, Read};usestd::net::TcpStream;letmutstream = TcpStream::connect("127.0.0.1:7878")    .expect("Couldn't connect to the server...");stream.set_nonblocking(true).expect("set_nonblocking call failed");letmutbuf =vec![];loop{matchstream.read_to_end(&mutbuf) {Ok(_) =>break,Err(refe)ife.kind() == io::ErrorKind::WouldBlock => {// wait until network socket is ready, typically implemented            // via platform-specific APIs such as epoll or IOCPwait_for_fd();        }Err(e) =>panic!("encountered IO error: {e}"),    };};println!("bytes: {buf:?}");

Takes ownership of aTcpStream’s socket file descriptor.

Takes ownership of aTcpStream’s socket.

Returns the argument unchanged.

CallsU::from(self).

That is, this conversion is whatever the implementation ofFrom<T> for U chooses to do.