Struct mio::net::TcpSocket

pub struct TcpSocket { /* fields omitted */ }

A non-blocking TCP socket used to configure a stream or listener.

The TcpSocket type wraps the operating-system's socket handle. This type is used to configure the socket before establishing a connection or start listening for inbound connections.

The socket will be closed when the value is dropped.

Implementations

impl TcpSocket

pub fn new_v4() -> Result<TcpSocket>

Create a new IPv4 TCP socket.

This calls socket(2).

pub fn new_v6() -> Result<TcpSocket>

Create a new IPv6 TCP socket.

This calls socket(2).

pub fn bind(&self, addr: SocketAddr) -> Result<()>

Bind addr to the TCP socket.

pub fn connect(self, addr: SocketAddr) -> Result<TcpStream>

Connect the socket to addr.

This consumes the socket and performs the connect operation. Once the connection completes, the socket is now a non-blocking TcpStream and can be used as such.

pub fn listen(self, backlog: u32) -> Result<TcpListener>

Listen for inbound connections, converting the socket to a TcpListener.

pub fn set_reuseaddr(&self, reuseaddr: bool) -> Result<()>

Sets the value of SO_REUSEADDR on this socket.

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

Get the value of SO_REUSEADDR set on this socket.

pub fn set_reuseport(&self, reuseport: bool) -> Result<()>

Sets the value of SO_REUSEPORT on this socket. Only supported available in unix

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

Get the value of SO_REUSEPORT set on this socket. Only supported available in unix

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

Sets the value of SO_LINGER on this socket.

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

Gets the value of SO_LINGER on this socket

pub fn set_recv_buffer_size(&self, size: u32) -> Result<()>

Sets the value of SO_RCVBUF on this socket.

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

Get the value of SO_RCVBUF set on this socket.

Note that if set_recv_buffer_size has been called on this socket previously, the value returned by this function may not be the same as the argument provided to set_recv_buffer_size. This is for the following reasons:

• Most operating systems have minimum and maximum allowed sizes for the receive buffer, and will clamp the provided value if it is below the minimum or above the maximum. The minimum and maximum buffer sizes are OS-dependent.
• Linux will double the buffer size to account for internal bookkeeping data, and returns the doubled value from getsockopt(2). As per man 7 socket:

  Sets or gets the maximum socket receive buffer in bytes. The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using setsockopt(2), and this doubled value is returned by getsockopt(2).

pub fn set_send_buffer_size(&self, size: u32) -> Result<()>

Sets the value of SO_SNDBUF on this socket.

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

Get the value of SO_SNDBUF set on this socket.

Note that if set_send_buffer_size has been called on this socket previously, the value returned by this function may not be the same as the argument provided to set_send_buffer_size. This is for the following reasons:

• Most operating systems have minimum and maximum allowed sizes for the receive buffer, and will clamp the provided value if it is below the minimum or above the maximum. The minimum and maximum buffer sizes are OS-dependent.
• Linux will double the buffer size to account for internal bookkeeping data, and returns the doubled value from getsockopt(2). As per man 7 socket:

  Sets or gets the maximum socket send buffer in bytes. The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using setsockopt(2), and this doubled value is returned by getsockopt(2).

pub fn set_keepalive(&self, keepalive: bool) -> Result<()>

Sets whether keepalive messages are enabled to be sent on this socket.

This will set the SO_KEEPALIVE option on this socket.

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

Returns whether or not TCP keepalive probes will be sent by this socket.

pub fn set_keepalive_params(&self, keepalive: TcpKeepalive) -> Result<()>

Sets parameters configuring TCP keepalive probes for this socket.

The supported parameters depend on the operating system, and are configured using the TcpKeepalive struct. At a minimum, all systems support configuring the keepalive time: the time after which the OS will start sending keepalive messages on an idle connection.

Notes

• This will enable TCP keepalive on this socket, if it is not already enabled.
• On some platforms, such as Windows, any keepalive parameters not configured by the TcpKeepalive struct passed to this function may be overwritten with their default values. Therefore, this function should either only be called once per socket, or the same parameters should be passed every time it is called.

Examples

use mio::net::{TcpSocket, TcpKeepalive};
use std::time::Duration;

let socket = TcpSocket::new_v6()?;
let keepalive = TcpKeepalive::default()
    .with_time(Duration::from_secs(4));
    // Depending on the target operating system, we may also be able to
    // configure the keepalive probe interval and/or the number of retries
    // here as well.

socket.set_keepalive_params(keepalive)?;

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

Returns the amount of time after which TCP keepalive probes will be sent on idle connections.

If None, then keepalive messages are disabled.

This returns the value of SO_KEEPALIVE + IPPROTO_TCP on OpenBSD, NetBSD, and Haiku, TCP_KEEPALIVE on macOS and iOS, and TCP_KEEPIDLE on all other Unix operating systems. On Windows, it is not possible to access the value of TCP keepalive parameters after they have been set.

Some platforms specify this value in seconds, so sub-second specifications may be omitted.

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

Returns the time interval between TCP keepalive probes, if TCP keepalive is enabled on this socket.

If None, then keepalive messages are disabled.

This returns the value of TCP_KEEPINTVL on supported Unix operating systems. On Windows, it is not possible to access the value of TCP keepalive parameters after they have been set..

Some platforms specify this value in seconds, so sub-second specifications may be omitted.

pub fn get_keepalive_retries(&self) -> Result<Option<u32>>

Returns the maximum number of TCP keepalive probes that will be sent before dropping a connection, if TCP keepalive is enabled on this socket.

If None, then keepalive messages are disabled.

This returns the value of TCP_KEEPCNT on Unix operating systems that support this option. On Windows, it is not possible to access the value of TCP keepalive parameters after they have been set.

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

Returns the local address of this socket

Will return Err result in windows if called before calling bind

Trait Implementations

impl AsRawFd for TcpSocket

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for TcpSocket

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

Formats the value using the given formatter.

impl Drop for TcpSocket

fn drop(&mut self)

Executes the destructor for this type.

impl FromRawFd for TcpSocket

unsafe fn from_raw_fd(fd: RawFd) -> TcpSocket

Converts a RawFd to a TcpSocket.

Notes

The caller is responsible for ensuring that the socket is in non-blocking mode.

impl IntoRawFd for TcpSocket

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor.