Struct std::net::TcpListener

1.0.0 · source ·
pub struct TcpListener(/* private fields */);
Expand description

A TCP socket server, listening for connections.

After creating a TcpListener by binding it to a socket address, it listens for incoming TCP connections. These can be accepted by calling accept or by iterating over the Incoming iterator returned by incoming.

The socket will be closed when the value is dropped.

The Transmission Control Protocol is specified in IETF RFC 793.

§Examples

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

fn handle_client(stream: TcpStream) {
    // ...
}

fn main() -> std::io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:80")?;

    // accept connections and process them serially
    for stream in listener.incoming() {
        handle_client(stream?);
    }
    Ok(())
}
Run

Implementations§

source§

impl TcpListener

source

pub fn bind<A: ToSocketAddrs>(addr: A) -> Result<TcpListener>

Creates a new TcpListener which will be bound to the specified address.

The returned listener is ready for accepting connections.

Binding with a port number of 0 will request that the OS assigns a port to this listener. The port allocated can be queried via the TcpListener::local_addr method.

The address type can be any implementor of ToSocketAddrs trait. See its documentation for concrete examples.

If addr yields multiple addresses, bind will be attempted with each of the addresses until one succeeds and returns the listener. If none of the addresses succeed in creating a listener, the error returned from the last attempt (the last address) is returned.

§Examples

Creates a TCP listener bound to 127.0.0.1:80:

use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:80").unwrap();
Run

Creates a TCP listener bound to 127.0.0.1:80. If that fails, create a TCP listener bound to 127.0.0.1:443:

use std::net::{SocketAddr, TcpListener};

let addrs = [
    SocketAddr::from(([127, 0, 0, 1], 80)),
    SocketAddr::from(([127, 0, 0, 1], 443)),
];
let listener = TcpListener::bind(&addrs[..]).unwrap();
Run

Creates a TCP listener bound to a port assigned by the operating system at 127.0.0.1.

use std::net::TcpListener;

let socket = TcpListener::bind("127.0.0.1:0").unwrap();
Run
source

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

Returns the local socket address of this listener.

§Examples
use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpListener};

let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
assert_eq!(listener.local_addr().unwrap(),
           SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080)));
Run
source

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

Creates a new independently owned handle to the underlying socket.

The returned TcpListener is a reference to the same socket that this object references. Both handles can be used to accept incoming connections and options set on one listener will affect the other.

§Examples
use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
let listener_clone = listener.try_clone().unwrap();
Run
source

pub fn accept(&self) -> Result<(TcpStream, SocketAddr)>

Accept a new incoming connection from this listener.

This function will block the calling thread until a new TCP connection is established. When established, the corresponding TcpStream and the remote peer’s address will be returned.

§Examples
use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:8080").unwrap();
match listener.accept() {
    Ok((_socket, addr)) => println!("new client: {addr:?}"),
    Err(e) => println!("couldn't get client: {e:?}"),
}
Run
source

pub fn incoming(&self) -> Incoming<'_>

Returns an iterator over the connections being received on this listener.

The returned iterator will never return None and will also not yield the peer’s SocketAddr structure. Iterating over it is equivalent to calling TcpListener::accept in a loop.

§Examples
use std::net::{TcpListener, TcpStream};

fn handle_connection(stream: TcpStream) {
   //...
}

fn main() -> std::io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:80")?;

    for stream in listener.incoming() {
        match stream {
            Ok(stream) => {
                handle_connection(stream);
            }
            Err(e) => { /* connection failed */ }
        }
    }
    Ok(())
}
Run
source

pub fn into_incoming(self) -> IntoIncoming

🔬This is a nightly-only experimental API. (tcplistener_into_incoming #88339)

Turn this into an iterator over the connections being received on this listener.

The returned iterator will never return None and will also not yield the peer’s SocketAddr structure. Iterating over it is equivalent to calling TcpListener::accept in a loop.

§Examples
#![feature(tcplistener_into_incoming)]
use std::net::{TcpListener, TcpStream};

fn listen_on(port: u16) -> impl Iterator<Item = TcpStream> {
    let listener = TcpListener::bind(("127.0.0.1", port)).unwrap();
    listener.into_incoming()
        .filter_map(Result::ok) /* Ignore failed connections */
}

fn main() -> std::io::Result<()> {
    for stream in listen_on(80) {
        /* handle the connection here */
    }
    Ok(())
}
Run
1.9.0 · source

pub 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::TcpListener;

let listener = TcpListener::bind("127.0.0.1:80").unwrap();
listener.set_ttl(100).expect("could not set TTL");
Run
1.9.0 · source

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

Gets the value of the IP_TTL option for this socket.

For more information about this option, see TcpListener::set_ttl.

§Examples
use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:80").unwrap();
listener.set_ttl(100).expect("could not set TTL");
assert_eq!(listener.ttl().unwrap_or(0), 100);
Run
1.9.0 · source

pub fn set_only_v6(&self, only_v6: bool) -> Result<()>

👎Deprecated since 1.16.0: this option can only be set before the socket is bound
1.9.0 · source

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

👎Deprecated since 1.16.0: this option can only be set before the socket is bound
1.9.0 · source

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

Gets 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::TcpListener;

let listener = TcpListener::bind("127.0.0.1:80").unwrap();
listener.take_error().expect("No error was expected");
Run
1.9.0 · source

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

Moves this TCP stream into or out of nonblocking mode.

This will result in the accept operation becoming nonblocking, i.e., immediately returning from their calls. If the IO operation is successful, Ok is returned and no further action is required. If the IO operation could not be completed and needs to be retried, an error with kind io::ErrorKind::WouldBlock is returned.

On Unix platforms, calling this method corresponds to calling fcntl FIONBIO. On Windows calling this method corresponds to calling ioctlsocket FIONBIO.

§Examples

Bind a TCP listener to an address, listen for connections, and read bytes in nonblocking mode:

use std::io;
use std::net::TcpListener;

let listener = TcpListener::bind("127.0.0.1:7878").unwrap();
listener.set_nonblocking(true).expect("Cannot set non-blocking");

for stream in listener.incoming() {
    match stream {
        Ok(s) => {
            // do something with the TcpStream
            handle_connection(s);
        }
        Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => {
            // wait until network socket is ready, typically implemented
            // via platform-specific APIs such as epoll or IOCP
            wait_for_fd();
            continue;
        }
        Err(e) => panic!("encountered IO error: {e}"),
    }
}
Run

Trait Implementations§

1.63.0 · source§

impl AsFd for TcpListener

source§

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor. Read more
source§

impl AsRawFd for TcpListener

source§

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor. Read more
source§

impl AsRawSocket for TcpListener

Available on Windows only.
source§

fn as_raw_socket(&self) -> RawSocket

Extracts the raw socket. Read more
1.63.0 · source§

impl AsSocket for TcpListener

Available on Windows only.
source§

fn as_socket(&self) -> BorrowedSocket<'_>

Borrows the socket.
source§

impl Debug for TcpListener

source§

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

Formats the value using the given formatter. Read more
1.63.0 · source§

impl From<OwnedFd> for TcpListener

source§

fn from(owned_fd: OwnedFd) -> Self

Converts to this type from the input type.
1.63.0 · source§

impl From<OwnedSocket> for TcpListener

Available on Windows only.
source§

fn from(owned: OwnedSocket) -> Self

Converts to this type from the input type.
1.63.0 · source§

impl From<TcpListener> for OwnedFd

source§

fn from(tcp_listener: TcpListener) -> OwnedFd

Converts to this type from the input type.
1.63.0 · source§

impl From<TcpListener> for OwnedSocket

Available on Windows only.
source§

fn from(tcp_listener: TcpListener) -> OwnedSocket

Converts to this type from the input type.
1.1.0 · source§

impl FromRawFd for TcpListener

source§

unsafe fn from_raw_fd(fd: RawFd) -> TcpListener

Constructs a new instance of Self from the given raw file descriptor. Read more
1.1.0 · source§

impl FromRawSocket for TcpListener

Available on Windows only.
source§

unsafe fn from_raw_socket(sock: RawSocket) -> TcpListener

Constructs a new I/O object from the specified raw socket. Read more
1.4.0 · source§

impl IntoRawFd for TcpListener

source§

fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor. Read more
1.4.0 · source§

impl IntoRawSocket for TcpListener

Available on Windows only.
source§

fn into_raw_socket(self) -> RawSocket

Consumes this object, returning the raw underlying socket. Read more
source§

impl TcpListenerExt for TcpListener

Available on WASI only.
source§

fn sock_accept(&self, flags: u16) -> Result<u32>

🔬This is a nightly-only experimental API. (wasi_ext #71213)
Accept a socket. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

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

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.