Struct std::net::TcpStream

pub struct TcpStream(_);

本地套接字和远程套接字之间的 TCP 流。

在通过 connect 到远程主机或 accept 在 TcpListener 上创建连接来创建 TcpStream 后，数据可以由 reading 和 writing 传输到该 TcpStream。

丢弃该值时，连接将关闭。也可以使用 shutdown 方法单独关闭连接的读取和写入部分。

传输控制协议在 IETF RFC 793 中指定。

Examples

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

fn main() -> std::io::Result<()> {
    let mut stream = TcpStream::connect("127.0.0.1:34254")?;

    stream.write(&[1])?;
    stream.read(&mut [0; 128])?;
    Ok(())
} // 流在这里关闭

Implementations

impl TcpStream

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

打开到远程主机的 TCP 连接。

addr 是远程主机的地址。 可以提供任何实现 ToSocketAddrs trait 的地址。有关具体示例，请参见此 trait 文档。

如果 addr 产生多个地址，则将使用每个地址尝试 connect，直到连接成功。 如果没有一个地址导致连接成功，则返回从上一次连接尝试 (最后一个地址) 返回的错误。

Examples

打开到 127.0.0.1:8080 的 TCP 连接:

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...");
}

打开到 127.0.0.1:8080 的 TCP 连接。如果连接失败，请打开与 127.0.0.1:8081 的 TCP 连接:

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...");
}

pub fn connect_timeout(
    addr: &SocketAddr,
    timeout: Duration
) -> Result<TcpStream>

超时打开与远程主机的 TCP 连接。

与 connect 不同，由于必须将超时应用于单个地址，因此 connect_timeout 仅占用一个 SocketAddr。

向此函数传递零 Duration 是错误的。

与 TcpStream 上的其他方法不同，这并不对应于单个系统调用。 相反，它以非阻塞模式调用 connect，然后使用特定于 OS 的机制来等待连接请求的完成。

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

返回此 TCP 连接的远程对等方的套接字地址。

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)));

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

返回此 TCP 连接本地一半的套接字地址。

Examples

use std::net::{IpAddr, Ipv4Addr, TcpStream};

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

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

关闭此连接的读取，写入或两半。

此函数将导致指定部分上的所有未决和 future I/O 立即以适当的值返回 (请参见 Shutdown 的文档)。

平台特定的行为

取决于操作系统，多次调用此函数可能会导致不同的行为。 在 Linux 上，第二个调用将返回 Ok(())，但在 macOS 上，它将返回 ErrorKind::NotConnected。 future 可能会改变。

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");

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

为基础套接字创建一个新的独立拥有的句柄。

返回的 TcpStream 是与此 object 引用相同的流的引用。 两个句柄将读取和写入相同的数据流，并且在一个流上设置的选项将传播到另一流。

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...");

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

将读取超时设置为指定的超时。

如果指定的值为 None，则 read 调用将无限期阻塞。 如果将零 Duration 传递给此方法，则返回 Err。

平台特定的行为

由于设置此选项而导致读取超时时，平台可能会返回不同的错误代码。 例如，Unix 通常返回类型为 WouldBlock 的错误，但是 Windows 可能返回 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");

如果将零 Duration 传递给此方法，则返回 Err:

use std::io;
use std::net::TcpStream;
use std::time::Duration;

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

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

将写超时设置为指定的超时。

如果指定的值为 None，则 write 调用将无限期阻塞。 如果将零 Duration 传递给此方法，则返回 Err。

平台特定的行为

由于设置此选项而导致写超时时，平台可能会返回不同的错误代码。 例如，Unix 通常返回类型为 WouldBlock 的错误，但是 Windows 可能返回 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");

如果将零 Duration 传递给此方法，则返回 Err:

use std::io;
use std::net::TcpStream;
use std::time::Duration;

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

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

返回此套接字的读取超时。

如果超时为 None，则 read 调用将无限期阻塞。

平台特定的行为

某些平台不提供对当前超时的访问。

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);

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

返回此套接字的写入超时。

如果超时为 None，则 write 调用将无限期阻塞。

平台特定的行为

某些平台不提供对当前超时的访问。

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);

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

从套接字所连接的远程地址接收套接字上的数据，而无需从队列中删除该数据。

成功时，返回偷看的字节数。

连续调用返回相同的数据。 这是通过将 MSG_PEEK 作为标志传递到基础 recv 系统调用来完成的。

Examples

use std::net::TcpStream;

let stream = TcpStream::connect("127.0.0.1:8000")
                       .expect("couldn't bind to address");
let mut buf = [0; 10];
let len = stream.peek(&mut buf).expect("peek failed");

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

设置此套接字上 TCP_NODELAY 选项的值。

如果设置，则此选项禁用 Nagle 算法。 这意味着即使只有少量数据，也总是尽快发送段。 如果未设置，则对数据进行缓冲，直到有足够的数据量可以发送出去，从而避免了频繁发送小数据包。

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");

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

获取此套接字上 TCP_NODELAY 选项的值。

有关此选项的更多信息，请参见 TcpStream::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);

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

设置此套接字上 IP_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");

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

获取此套接字的 IP_TTL 选项的值。

有关此选项的更多信息，请参见 TcpStream::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);

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

获取此套接字上 SO_ERROR 选项的值。

这将检索存储在基础套接字中的错误，从而清除进程中的字段。 这对于检查两次调用之间的错误很有用。

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...");

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

将此 TCP 流移入或移出非阻塞模式。

这将导致 read，write，recv 和 send 操作变为非阻塞，即立即从其调用中返回。

如果 IO 操作成功，则返回 Ok，并且不需要进一步的操作。 如果 IO 操作无法完成，需要重试，则返回类型为 io::ErrorKind::WouldBlock 的错误。

在 Unix 平台上，调用此方法相当于调用 fcntl FIONBIO。 在 Windows 上，调用此方法对应于调用 ioctlsocket FIONBIO。

Examples

在非阻塞模式下从 TCP 流读取字节:

use std::io::{self, Read};
use std::net::TcpStream;

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

let mut buf = vec![];
loop {
    match stream.read_to_end(&mut buf) {
        Ok(_) => break,
        Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
            // 等待网络套接字就绪，通常通过平台特定的 API (例如 epoll 或 IOCP) 实现
            wait_for_fd();
        }
        Err(e) => panic!("encountered IO error: {}", e),
    };
};
println!("bytes: {:?}", buf);

Trait Implementations

impl AsRawFd for TcpStream

This is supported on Unix only.

fn as_raw_fd(&self) -> RawFd

提取原始文件描述符。

impl AsRawFd for TcpStream

This is supported on WASI only.

fn as_raw_fd(&self) -> RawFd

🔬 This is a nightly-only experimental API. (wasi_ext #71213)

提取原始文件描述符。

impl AsRawSocket for TcpStream

This is supported on Windows only.

fn as_raw_socket(&self) -> RawSocket

从此 object 中提取基础原始套接字。

impl Debug for TcpStream

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

使用给定的格式化程序格式化该值。

impl FromRawFd for TcpStream

This is supported on Unix only.

unsafe fn from_raw_fd(fd: RawFd) -> TcpStream

根据给定的原始文件描述符构造 Self 的新实例。

impl FromRawFd for TcpStream

This is supported on WASI only.

unsafe fn from_raw_fd(fd: RawFd) -> TcpStream

🔬 This is a nightly-only experimental API. (wasi_ext #71213)

根据给定的原始文件描述符构造 Self 的新实例。

impl FromRawSocket for TcpStream

This is supported on Windows only.

unsafe fn from_raw_socket(sock: RawSocket) -> TcpStream

从给定的原始套接字创建一个新的 I/O object。

impl IntoRawFd for TcpStream

This is supported on Unix only.

fn into_raw_fd(self) -> RawFd

使用此 object，返回原始基础文件描述符。

impl IntoRawFd for TcpStream

This is supported on WASI only.

fn into_raw_fd(self) -> RawFd

🔬 This is a nightly-only experimental API. (wasi_ext #71213)

使用此 object，返回原始基础文件描述符。

impl IntoRawSocket for TcpStream

This is supported on Windows only.

fn into_raw_socket(self) -> RawSocket

消耗此对象，返回原始基础套接字。

impl Read for TcpStream

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

从该源中提取一些字节到指定的缓冲区中，返回读取的字节数。

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

与 read 相似，不同之处在于它读入缓冲区的一部分。

fn is_read_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector #69941)

确定此 Read 是否具有有效的 read_vectored 实现。

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer #42788)

确定该 Reader 是否可以与未初始化内存的缓冲区一起使用。

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

读取所有字节，直到此源中的 EOF 为止，然后将它们放入 buf。

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

读取所有字节，直到该源中的 EOF 为止，然后将它们附加到 buf。

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

读取填充 buf 所需的确切字节数。

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

为此 Read 实例创建 “by reference” 适配器。

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

将此 Read 实例的字节数转换为 Iterator。

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

创建一个适配器，它将将此流与另一个流链接。

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

创建一个适配器，该适配器最多可以从中读取 limit 字节。

impl Read for &TcpStream

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

从该源中提取一些字节到指定的缓冲区中，返回读取的字节数。

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize>

与 read 相似，不同之处在于它读入缓冲区的一部分。

fn is_read_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector #69941)

确定此 Read 是否具有有效的 read_vectored 实现。

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer #42788)

确定该 Reader 是否可以与未初始化内存的缓冲区一起使用。

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

读取所有字节，直到此源中的 EOF 为止，然后将它们放入 buf。

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

读取所有字节，直到该源中的 EOF 为止，然后将它们附加到 buf。

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

读取填充 buf 所需的确切字节数。

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

为此 Read 实例创建 “by reference” 适配器。

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

将此 Read 实例的字节数转换为 Iterator。

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

创建一个适配器，它将将此流与另一个流链接。

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

创建一个适配器，该适配器最多可以从中读取 limit 字节。

impl Write for TcpStream

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

在此 writer 中写入一个缓冲区，返回写入的字节数。

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

类似于 write，不同之处在于它是从缓冲区片段中写入数据的。

fn is_write_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector #69941)

确定此 Writer 是否具有有效的 write_vectored 实现。

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

刷新此输出流，确保所有中间缓冲的内容均到达其目的地。

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

尝试将整个缓冲区写入此 writer。

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>

🔬 This is a nightly-only experimental API. (write_all_vectored #70436)

尝试将多个缓冲区写入此 writer。

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

将格式化的字符串写入此 writer，返回遇到的任何错误。

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

为此 Write 实例创建 “by reference” 适配器。

impl Write for &TcpStream

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

在此 writer 中写入一个缓冲区，返回写入的字节数。

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize>

类似于 write，不同之处在于它是从缓冲区片段中写入数据的。

fn is_write_vectored(&self) -> bool

🔬 This is a nightly-only experimental API. (can_vector #69941)

确定此 Writer 是否具有有效的 write_vectored 实现。

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

刷新此输出流，确保所有中间缓冲的内容均到达其目的地。

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

尝试将整个缓冲区写入此 writer。

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<()>

🔬 This is a nightly-only experimental API. (write_all_vectored #70436)

尝试将多个缓冲区写入此 writer。

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

将格式化的字符串写入此 writer，返回遇到的任何错误。

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

为此 Write 实例创建 “by reference” 适配器。