Struct std::net::TcpListener
1.0.0 · source · [−]pub struct TcpListener(_);
Expand description
A TCP socket server, listening for connections.
After creating a TcpListener
by bind
ing 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(())
}
RunImplementations
sourceimpl TcpListener
impl TcpListener
sourcepub fn bind<A: ToSocketAddrs>(addr: A) -> Result<TcpListener>
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();
RunCreates 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();
Runsourcepub fn local_addr(&self) -> Result<SocketAddr>
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)));
Runsourcepub fn try_clone(&self) -> Result<TcpListener>
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();
Runsourcepub fn accept(&self) -> Result<(TcpStream, SocketAddr)>
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:?}"),
}
Runsourcepub fn incoming(&self) -> Incoming<'_>ⓘNotable traits for Incoming<'a>impl<'a> Iterator for Incoming<'a> type Item = Result<TcpStream>;
pub fn incoming(&self) -> Incoming<'_>ⓘNotable traits for Incoming<'a>impl<'a> Iterator for Incoming<'a> type Item = Result<TcpStream>;
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").unwrap();
for stream in listener.incoming() {
match stream {
Ok(stream) => {
handle_connection(stream);
}
Err(e) => { /* connection failed */ }
}
}
Ok(())
}
Runsourcepub fn into_incoming(self) -> IntoIncomingⓘNotable traits for IntoIncomingimpl Iterator for IntoIncoming type Item = Result<TcpStream>;
pub fn into_incoming(self) -> IntoIncomingⓘNotable traits for IntoIncomingimpl Iterator for IntoIncoming type Item = Result<TcpStream>;
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:80").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(())
}
Run1.9.0 · sourcepub fn ttl(&self) -> Result<u32>
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);
Runpub fn set_only_v6(&self, only_v6: bool) -> Result<()>
this option can only be set before the socket is bound
pub fn only_v6(&self) -> Result<bool>
this option can only be set before the socket is bound
1.9.0 · sourcepub fn take_error(&self) -> Result<Option<Error>>
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");
Run1.9.0 · sourcepub fn set_nonblocking(&self, nonblocking: bool) -> Result<()>
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}"),
}
}
RunTrait Implementations
1.63.0 · sourceimpl AsFd for TcpListener
impl AsFd for TcpListener
sourcefn as_fd(&self) -> BorrowedFd<'_>
fn as_fd(&self) -> BorrowedFd<'_>
Borrows the file descriptor. Read more
sourceimpl AsRawFd for TcpListener
impl AsRawFd for TcpListener
sourceimpl AsRawSocket for TcpListener
Available on Windows only.
impl AsRawSocket for TcpListener
sourcefn as_raw_socket(&self) -> RawSocket
fn as_raw_socket(&self) -> RawSocket
Extracts the raw socket. Read more
1.63.0 · sourceimpl AsSocket for TcpListener
Available on Windows only.
impl AsSocket for TcpListener
sourcefn as_socket(&self) -> BorrowedSocket<'_>
fn as_socket(&self) -> BorrowedSocket<'_>
Borrows the socket.
sourceimpl Debug for TcpListener
impl Debug for TcpListener
1.63.0 · sourceimpl From<OwnedFd> for TcpListener
impl From<OwnedFd> for TcpListener
1.63.0 · sourceimpl From<OwnedSocket> for TcpListener
Available on Windows only.
impl From<OwnedSocket> for TcpListener
sourcefn from(owned: OwnedSocket) -> Self
fn from(owned: OwnedSocket) -> Self
Converts to this type from the input type.
1.63.0 · sourceimpl From<TcpListener> for OwnedFd
impl From<TcpListener> for OwnedFd
sourcefn from(tcp_listener: TcpListener) -> OwnedFd
fn from(tcp_listener: TcpListener) -> OwnedFd
Converts to this type from the input type.
1.63.0 · sourceimpl From<TcpListener> for OwnedSocket
Available on Windows only.
impl From<TcpListener> for OwnedSocket
sourcefn from(tcp_listener: TcpListener) -> OwnedSocket
fn from(tcp_listener: TcpListener) -> OwnedSocket
Converts to this type from the input type.
1.1.0 · sourceimpl FromRawFd for TcpListener
impl FromRawFd for TcpListener
sourceunsafe fn from_raw_fd(fd: RawFd) -> TcpListener
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 · sourceimpl FromRawSocket for TcpListener
Available on Windows only.
impl FromRawSocket for TcpListener
sourceunsafe fn from_raw_socket(sock: RawSocket) -> TcpListener
unsafe fn from_raw_socket(sock: RawSocket) -> TcpListener
Constructs a new I/O object from the specified raw socket. Read more
1.4.0 · sourceimpl IntoRawFd for TcpListener
impl IntoRawFd for TcpListener
sourcefn into_raw_fd(self) -> RawFd
fn into_raw_fd(self) -> RawFd
Consumes this object, returning the raw underlying file descriptor. Read more
1.4.0 · sourceimpl IntoRawSocket for TcpListener
Available on Windows only.
impl IntoRawSocket for TcpListener
sourcefn into_raw_socket(self) -> RawSocket
fn into_raw_socket(self) -> RawSocket
Consumes this object, returning the raw underlying socket. Read more
sourceimpl TcpListenerExt for TcpListener
Available on WASI only.
impl TcpListenerExt for TcpListener
Auto Trait Implementations
impl RefUnwindSafe for TcpListener
impl Send for TcpListener
impl Sync for TcpListener
impl Unpin for TcpListener
impl UnwindSafe for TcpListener
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more