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]

#### `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 `local_addr` method.

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

# Examples

    use std::net::TcpListener;

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

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

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

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

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

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

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

#### `fn ttl(&self) -> Result<u32>`
1.9.0

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

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

Deprecated since 1.16.0

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

#### `fn only_v6(&self) -> Result<bool>`
1.9.0

Deprecated since 1.16.0

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

#### `fn take_error(&self) -> Result<Option<Error>>`
1.9.0

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

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

Moves this TCP stream into or out of nonblocking mode.

On Unix this corresponds to calling fcntl, and on Windows this corresponds to calling ioctlsocket.

# Examples

    use std::net::TcpListener;

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

## Trait Implementations

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

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

Formats the value using the given formatter.

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

#### `fn as_raw_fd(&self) -> RawFd`

Extracts the raw file descriptor. Read more

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

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

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`

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

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  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`)