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

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

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

    fn main() -> 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

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

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

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

Formats the value using the given formatter. Read more

## Auto Trait Implementations

### `impl Send for TcpListener`

### `impl Sync for TcpListener`

## Blanket Implementations

### `impl<T, U> TryFrom for T where
T: From<U>,` [src]

#### `type Error = !`

🔬 This is a nightly-only experimental API. (`try_from` #33417)

The type returned in the event of a conversion error.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

🔬 This is a nightly-only experimental API. (`try_from` #33417)

Performs the conversion.

### `impl<T> From for T`[src]

#### `fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> TryInto for T where
U: TryFrom<T>,` [src]

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

🔬 This is a nightly-only experimental API. (`try_from` #33417)

The type returned in the event of a conversion error.

#### `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

🔬 This is a nightly-only experimental API. (`try_from` #33417)

Performs the conversion.

### `impl<T, U> Into for T where
U: From<T>,` [src]

#### `fn into(self) -> U`[src]

Performs the conversion.

### `impl<T> Borrow for T where
T: ?Sized,` [src]

####
ⓘImportant traits for &'_ mut I

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'a, R: Read + ?Sized> Read for &'a mut Rimpl<'a, W: Write + ?Sized> Write for &'a mut W`
`fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut for T where
T: ?Sized,` [src]

####
ⓘImportant traits for &'_ mut I

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'a, R: Read + ?Sized> Read for &'a mut Rimpl<'a, W: Write + ?Sized> Write for &'a mut W`
`fn borrow_mut(&mut self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `fn get_type_id(&self) -> TypeId`[src]

🔬 This is a nightly-only experimental API. (`get_type_id` #27745)

this method will likely be replaced by an associated static

Gets the `TypeId` of `self`. 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
`+`
  Expand all sections
`-`
  Collapse 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`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)