std::net::TcpListener - Rust
Description: API documentation for the Rust `TcpListener` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, TcpListener

# Struct std::net::TcpListener 1.0.0 [−] [src]

    pub struct TcpListener(_);

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) {
        // ...
    }

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

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

## Methods

### `impl TcpListener`
[src]

#### `pub fn bind<A: ToSocketAddrs>(addr: A) -> Result<TcpListener>`
[src]

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 `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

Create 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

Create 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

#### `pub fn local_addr(&self) -> Result<SocketAddr>`
[src]

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

#### `pub fn try_clone(&self) -> Result<TcpListener>`
[src]

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

#### `pub fn accept(&self) -> Result<(TcpStream, SocketAddr)>`
[src]

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

####
ⓘImportant traits for Incoming<'a>

### Important traits for Incoming<'a>

`impl<'a> Iterator for Incoming<'a> type Item = Result<TcpStream>;`
`pub fn incoming(&self) -> Incoming`
[src]

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 `accept` in a loop.

# Examples

    use std::net::TcpListener;

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

    for stream in listener.incoming() {
        match stream {
            Ok(stream) => {
                println!("new client!");
            }
            Err(e) => { /* connection failed */ }
        }
    }Run

#### `pub fn set_ttl(&self, ttl: u32) -> Result<()>`
1.9.0
[src]

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

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

Gets the value of the `IP_TTL` option for this socket.

For more information about this option, see `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

#### `pub fn set_only_v6(&self, only_v6: bool) -> Result<()>`
1.9.0
[src]

Deprecated since 1.16.0

: this option can only be set before the socket is bound

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

Deprecated since 1.16.0

: this option can only be set before the socket is bound

#### `pub fn take_error(&self) -> Result<Option<Error>>`
1.9.0
[src]

Get 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

#### `pub fn set_nonblocking(&self, nonblocking: bool) -> Result<()>`
1.9.0
[src]

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

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

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

Formats the value using the given formatter. Read more

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

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

This is supported on Unix only.

Extracts the raw file descriptor. Read more

### `impl FromRawFd for TcpListener`
1.1.0
[src]

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

This is supported on Unix only.

Constructs a new instance of `Self` from the given raw file descriptor. Read more

### `impl IntoRawFd for TcpListener`
1.4.0
[src]

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

This is supported on Unix only.

Consumes this object, returning the raw underlying file descriptor. Read more

### `impl AsRawSocket for TcpListener`
[src]

#### `fn as_raw_socket(&self) -> RawSocket`
[src]

This is supported on Windows only.

Extracts the underlying raw socket from this object.

### `impl FromRawSocket for TcpListener`
1.1.0
[src]

#### `unsafe fn from_raw_socket(sock: RawSocket) -> TcpListener`
[src]

This is supported on Windows only.

Creates a new I/O object from the given raw socket. Read more

### `impl IntoRawSocket for TcpListener`
1.4.0
[src]

#### `fn into_raw_socket(self) -> RawSocket`
[src]

This is supported on Windows only.

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

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
↑
  Move up in search results
↓
  Move down in search results
↹
  Switch tab
⏎
  Go to active search result
+ / -
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)