# [−] [src] Struct tokio::net::TcpSocket

    pub struct TcpSocket { /* fields omitted */ }

A TCP socket that has not yet been converted to a `TcpStream` or `TcpListener`.

`TcpSocket` wraps an operating system socket and enables the caller to configure the socket before establishing a TCP connection or accepting inbound connections. The caller is able to set socket option and explicitly bind the socket with a socket address.

The underlying socket is closed when the `TcpSocket` value is dropped.

`TcpSocket` should only be used directly if the default configuration used by `TcpStream::connect` and `TcpListener::bind` does not meet the required use case.

Calling `TcpStream::connect("127.0.0.1:8080")` is equivalent to:

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();

        let socket = TcpSocket::new_v4()?;
        let stream = socket.connect(addr).await?;

        Ok(())
    }

Calling `TcpListener::bind("127.0.0.1:8080")` is equivalent to:

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();

        let socket = TcpSocket::new_v4()?;
        // On platforms with Berkeley-derived sockets, this allows to quickly
        // rebind a socket, without needing to wait for the OS to clean up the
        // previous one.
        //
        // On Windows, this allows rebinding sockets which are actively in use,
        // which allows “socket hijacking”, so we explicitly don't set it here.
        // https://docs.microsoft.com/en-us/windows/win32/winsock/using-so-reuseaddr-and-so-exclusiveaddruse
        socket.set_reuseaddr(true)?;
        socket.bind(addr)?;

        let listener = socket.listen(1024)?;

        Ok(())
    }

Setting socket options not explicitly provided by `TcpSocket` may be done by accessing the `RawFd`/`RawSocket` using `AsRawFd`/`AsRawSocket` and setting the option with a crate like `socket2`.

## Implementations

### `impl TcpSocket` [src]

#### `pub fn new_v4() -> Result<TcpSocket>` [src]

Create a new socket configured for IPv4.

Calls `socket(2)` with `AF_INET` and `SOCK_STREAM`.

# Returns

On success, the newly created `TcpSocket` is returned. If an error is encountered, it is returned instead.

# Examples

Create a new IPv4 socket and start listening.

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();
        let socket = TcpSocket::new_v4()?;
        socket.bind(addr)?;

        let listener = socket.listen(128)?;
        Ok(())
    }

#### `pub fn new_v6() -> Result<TcpSocket>` [src]

Create a new socket configured for IPv6.

Calls `socket(2)` with `AF_INET6` and `SOCK_STREAM`.

# Returns

On success, the newly created `TcpSocket` is returned. If an error is encountered, it is returned instead.

# Examples

Create a new IPv6 socket and start listening.

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "[::1]:8080".parse().unwrap();
        let socket = TcpSocket::new_v6()?;
        socket.bind(addr)?;

        let listener = socket.listen(128)?;
        Ok(())
    }

#### `pub fn set_reuseaddr(&self, reuseaddr: bool) -> Result<()>` [src]

Allow the socket to bind to an in-use address.

Behavior is platform specific. Refer to the target platform's documentation for more details.

# Examples

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();

        let socket = TcpSocket::new_v4()?;
        socket.set_reuseaddr(true)?;
        socket.bind(addr)?;

        let listener = socket.listen(1024)?;

        Ok(())
    }

#### `pub fn reuseaddr(&self) -> Result<bool>` [src]

Retrieves the value set for `SO_REUSEADDR` on this socket

# Examples

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();

        let socket = TcpSocket::new_v4()?;
        socket.set_reuseaddr(true)?;
        assert!(socket.reuseaddr().unwrap());
        socket.bind(addr)?;

        let listener = socket.listen(1024)?;
        Ok(())
    }

#### `pub fn set_reuseport(&self, reuseport: bool) -> Result<()>` [src]

Allow the socket to bind to an in-use port. Only available for unix systems (excluding Solaris & Illumos).

Behavior is platform specific. Refer to the target platform's documentation for more details.

# Examples

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();

        let socket = TcpSocket::new_v4()?;
        socket.set_reuseport(true)?;
        socket.bind(addr)?;

        let listener = socket.listen(1024)?;
        Ok(())
    }

#### `pub fn reuseport(&self) -> Result<bool>` [src]

Allow the socket to bind to an in-use port. Only available for unix systems (excluding Solaris & Illumos).

Behavior is platform specific. Refer to the target platform's documentation for more details.

# Examples

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();

        let socket = TcpSocket::new_v4()?;
        socket.set_reuseport(true)?;
        assert!(socket.reuseport().unwrap());
        socket.bind(addr)?;

        let listener = socket.listen(1024)?;
        Ok(())
    }

#### `pub fn set_send_buffer_size(&self, size: u32) -> Result<()>` [src]

Sets the size of the TCP send buffer on this socket.

On most operating systems, this sets the `SO_SNDBUF` socket option.

#### `pub fn send_buffer_size(&self) -> Result<u32>` [src]

Returns the size of the TCP send buffer for this socket.

On most operating systems, this is the value of the `SO_SNDBUF` socket option.

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 send 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_recv_buffer_size(&self, size: u32) -> Result<()>` [src]

Sets the size of the TCP receive buffer on this socket.

On most operating systems, this sets the `SO_RCVBUF` socket option.

#### `pub fn recv_buffer_size(&self) -> Result<u32>` [src]

Returns the size of the TCP receive buffer for this socket.

On most operating systems, this is the value of the `SO_RCVBUF` socket option.

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_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 local_addr(&self) -> Result<SocketAddr>` [src]

Get the local address of this socket.

Will fail on windows if called before `bind`.

# Examples

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();

        let socket = TcpSocket::new_v4()?;
        socket.bind(addr)?;
        assert_eq!(socket.local_addr().unwrap().to_string(), "127.0.0.1:8080");
        let listener = socket.listen(1024)?;
        Ok(())
    }

#### `pub fn bind(&self, addr: SocketAddr) -> Result<()>` [src]

Bind the socket to the given address.

This calls the `bind(2)` operating-system function. Behavior is platform specific. Refer to the target platform's documentation for more details.

# Examples

Bind a socket before listening.

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();

        let socket = TcpSocket::new_v4()?;
        socket.bind(addr)?;

        let listener = socket.listen(1024)?;

        Ok(())
    }

#### `pub async fn connect(self, addr: SocketAddr) -> Result<TcpStream>` [src]

Establish a TCP connection with a peer at the specified socket address.

The `TcpSocket` is consumed. Once the connection is established, a connected `TcpStream` is returned. If the connection fails, the encountered error is returned.

This calls the `connect(2)` operating-system function. Behavior is platform specific. Refer to the target platform's documentation for more details.

# Examples

Connecting to a peer.

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();

        let socket = TcpSocket::new_v4()?;
        let stream = socket.connect(addr).await?;

        Ok(())
    }

#### `pub fn listen(self, backlog: u32) -> Result<TcpListener>` [src]

Convert the socket into a `TcpListener`.

`backlog` defines the maximum number of pending connections are queued by the operating system at any given time. Connection are removed from the queue with `TcpListener::accept`. When the queue is full, the operationg-system will start rejecting connections.

This calls the `listen(2)` operating-system function, marking the socket as a passive socket. Behavior is platform specific. Refer to the target platform's documentation for more details.

# Examples

Create a `TcpListener`.

    use tokio::net::TcpSocket;

    use std::io;

    #[tokio::main]
    async fn main() -> io::Result<()> {
        let addr = "127.0.0.1:8080".parse().unwrap();

        let socket = TcpSocket::new_v4()?;
        socket.bind(addr)?;

        let listener = socket.listen(1024)?;

        Ok(())
    }

## Trait Implementations

### `impl AsRawFd for TcpSocket` [src]

#### `fn as_raw_fd(&self) -> RawFd` [src]

Extracts the raw file descriptor. Read more

### `impl Debug for TcpSocket` [src]

#### `fn fmt(&self, fmt: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `impl FromRawFd for TcpSocket` [src]

#### `unsafe fn from_raw_fd(fd: RawFd) -> TcpSocket` [src]

Converts a `RawFd` to a `TcpSocket`.

# Notes

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

## Auto Trait Implementations

### `impl RefUnwindSafe for TcpSocket`

### `impl Send for TcpSocket`

### `impl Sync for TcpSocket`

### `impl Unpin for TcpSocket`

### `impl UnwindSafe for TcpSocket`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut F

`impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized, type Output = <F as Future>::Output;`
` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.