Struct std::net::TcpStream

pub struct TcpStream(_);

A structure which represents a TCP stream between a local socket and a remote socket.

The socket will be closed when the value is dropped.

Examples

use std::io::prelude::*;
use std::net::TcpStream;

{
    let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap();

    // ignore the Result
    let _ = stream.write(&[1]);
    let _ = stream.read(&mut [0; 128]); // ignore here too
} // the stream is closed here

Methods

impl TcpStream

fn connect<A: ToSocketAddrs>(addr: A) -> Result<TcpStream>

Opens a TCP connection to a remote host.

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.

Examples

use std::net::TcpStream;

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

fn peer_addr(&self) -> Result<SocketAddr>

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

Examples

use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpStream};

let stream = 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)));

fn local_addr(&self) -> Result<SocketAddr>

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

Examples

use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpStream};

let stream = TcpStream::connect("127.0.0.1:8080")
                       .expect("Couldn't connect to the server...");
assert_eq!(stream.local_addr().unwrap(),
           SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080)));

fn shutdown(&self, how: Shutdown) -> Result<()>

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

This function will cause all pending and future I/O on the specified portions to return immediately with an appropriate value (see the documentation of Shutdown).

Examples

use std::net::{Shutdown, TcpStream};

let stream = TcpStream::connect("127.0.0.1:8080")
                       .expect("Couldn't connect to the server...");
stream.shutdown(Shutdown::Both).expect("shutdown call failed");

fn try_clone(&self) -> Result<TcpStream>

Creates a new independently owned handle to the underlying socket.

The returned TcpStream is a reference to the same stream that this object references. Both handles will read and write the same stream of data, and options set on one stream will be propagated to the other stream.

Examples

use std::net::TcpStream;

let stream = TcpStream::connect("127.0.0.1:8080")
                       .expect("Couldn't connect to the server...");
let stream_clone = stream.try_clone().expect("clone failed...");

fn set_read_timeout(&self, dur: Option<Duration>) -> Result<()>

Sets the read timeout to the timeout specified.

If the value specified is None, then read() calls will block indefinitely. It is an error to pass the zero Duration to this method.

Note

Platforms may return a different error code whenever a read times out as a result of setting this option. For example Unix typically returns an error of the kind WouldBlock, but Windows may return TimedOut.

Examples

use std::net::TcpStream;

let stream = 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");

fn set_write_timeout(&self, dur: Option<Duration>) -> Result<()>

Sets the write timeout to the timeout specified.

If the value specified is None, then write() calls will block indefinitely. It is an error to pass the zero Duration to this method.

Note

Platforms may return a different error code whenever a write times out as a result of setting this option. For example Unix typically returns an error of the kind WouldBlock, but Windows may return TimedOut.

Examples

use std::net::TcpStream;

let stream = 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");

fn read_timeout(&self) -> Result<Option<Duration>>

Returns the read timeout of this socket.

If the timeout is None, then read() calls will block indefinitely.

Note

Some platforms do not provide access to the current timeout.

Examples

use std::net::TcpStream;

let stream = 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);

fn write_timeout(&self) -> Result<Option<Duration>>

Returns the write timeout of this socket.

If the timeout is None, then write() calls will block indefinitely.

Note

Some platforms do not provide access to the current timeout.

Examples

use std::net::TcpStream;

let stream = 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);

fn set_nodelay(&self, nodelay: bool) -> Result<()>

Sets the value of the TCP_NODELAY option on this socket.

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

Examples

use std::net::TcpStream;

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

fn nodelay(&self) -> Result<bool>

Gets the value of the TCP_NODELAY option on this socket.

For more information about this option, see set_nodelay.

Examples

use std::net::TcpStream;

let stream = 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);

fn set_ttl(&self, ttl: u32) -> Result<()>

Sets the value for the IP_TTL option on this socket.

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

Examples

use std::net::TcpStream;

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

fn ttl(&self) -> Result<u32>

Gets the value of the IP_TTL option for this socket.

For more information about this option, see set_ttl.

Examples

use std::net::TcpStream;

let stream = 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);

fn take_error(&self) -> Result<Option<Error>>

Get the value of the SO_ERROR option on this socket.

This will retrieve the stored error in the underlying socket, clearing the field in the process. This can be useful for checking errors between calls.

Examples

use std::net::TcpStream;

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

fn set_nonblocking(&self, nonblocking: bool) -> Result<()>

Moves this TCP stream into or out of nonblocking mode.

On Unix this corresponds to calling fcntl, and on Windows this corresponds to calling ioctlsocket.

Examples

use std::net::TcpStream;

let stream = TcpStream::connect("127.0.0.1:8080")
                       .expect("Couldn't connect to the server...");
stream.set_nonblocking(true).expect("set_nonblocking call failed");

Trait Implementations

impl Read for TcpStream

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

Read all bytes until EOF in this source, placing them into buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self where Self: Sized

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self> where Self: Sized

Transforms this Read instance to an Iterator over its bytes.

fn chars(self) -> Chars<Self> where Self: Sized

🔬 This is a nightly-only experimental API.   (io #27802)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an Iterator over chars.

fn chain<R: Read>(self, next: R) -> Chain<Self, R> where Self: Sized

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self> where Self: Sized

Creates an adaptor which will read at most limit bytes from it.

impl Write for TcpStream

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this object, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this write.

fn write_fmt(&mut self, fmt: Arguments) -> Result<()>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self where Self: Sized

Creates a "by reference" adaptor for this instance of Write.

impl<'a> Read for &'a TcpStream

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize>

Read all bytes until EOF in this source, placing them into buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<()>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self where Self: Sized

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self> where Self: Sized

Transforms this Read instance to an Iterator over its bytes.

fn chars(self) -> Chars<Self> where Self: Sized

🔬 This is a nightly-only experimental API.   (io #27802)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an Iterator over chars.

fn chain<R: Read>(self, next: R) -> Chain<Self, R> where Self: Sized

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self> where Self: Sized

Creates an adaptor which will read at most limit bytes from it.

impl<'a> Write for &'a TcpStream

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this object, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<()>

Attempts to write an entire buffer into this write.

fn write_fmt(&mut self, fmt: Arguments) -> Result<()>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self where Self: Sized

Creates a "by reference" adaptor for this instance of Write.

impl Debug for TcpStream

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl AsRawFd for TcpStream

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl FromRawFd for TcpStream

unsafe fn from_raw_fd(fd: RawFd) -> TcpStream

Constructs a new instance of Self from the given raw file descriptor.

impl IntoRawFd for TcpStream

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.