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 structure representing a socket server.

# Examples

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

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

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

    // accept connections and process them, spawning a new thread for each one
    for stream in listener.incoming() {
        match stream {
            Ok(stream) => {
                handle_client(stream);
            }
            Err(e) => { /* connection failed */ }
        }
    }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.

# 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

Sets the value for the `IPV6_V6ONLY` option on this socket.

If this is set to `true` then the socket is restricted to sending and receiving IPv6 packets only. In this case two IPv4 and IPv6 applications can bind the same port at the same time.

If this is set to `false` then the socket can be used to send and receive packets from an IPv4-mapped IPv6 address.

# Examples

    use std::net::TcpListener;

    let listener = TcpListener::bind("127.0.0.1:80").unwrap();
    listener.set_only_v6(true).expect("Cannot set to IPv6");Run

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

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

For more information about this option, see `set_only_v6`.

# Examples

    use std::net::TcpListener;

    let listener = TcpListener::bind("127.0.0.1:80").unwrap();
    listener.set_only_v6(true).expect("Cannot set to IPv6");
    assert_eq!(listener.only_v6().unwrap_or(false), true);Run

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