Struct UnixListener 

pub struct UnixListener { /* private fields */ }

Available on Unix and crate feature net only.

A Unix socket which can accept connections from other Unix sockets.

You can accept a new connection by using the accept method.

A UnixListener can be turned into a Stream with UnixListenerStream.

Errors

Note that accepting a connection can lead to various errors and not all of them are necessarily fatal ‒ for example having too many open file descriptors or the other side closing the connection while it waits in an accept queue. These would terminate the stream if not handled in any way.

Examples

use tokio::net::UnixListener;

#[tokio::main]
async fn main() {
    let listener = UnixListener::bind("/path/to/the/socket").unwrap();
    loop {
        match listener.accept().await {
            Ok((stream, _addr)) => {
                println!("new client!");
            }
            Err(e) => { /* connection failed */ }
        }
    }
}

Implementations

impl UnixListener

pub fn bind<P>(path: P) -> Result<UnixListener>

where P: AsRef<Path>,

Available on non-loom only.

Creates a new UnixListener bound to the specified path.

Panics

This function panics if it is not called from within a runtime with IO enabled.

The runtime is usually set implicitly when this function is called from a future driven by a tokio runtime, otherwise runtime can be set explicitly with Runtime::enter function.

pub fn from_std(listener: UnixListener) -> Result<UnixListener>

Available on non-loom only.

Creates new UnixListener from a std::os::unix::net::UnixListener.

This function is intended to be used to wrap a UnixListener from the standard library in the Tokio equivalent.

Notes

The caller is responsible for ensuring that the listener is in non-blocking mode. Otherwise all I/O operations on the listener will block the thread, which will cause unexpected behavior. Non-blocking mode can be set using set_nonblocking.

Passing a listener in blocking mode is always erroneous, and the behavior in that case may change in the future. For example, it could panic.

Examples

use tokio::net::UnixListener;
use std::os::unix::net::UnixListener as StdUnixListener;

let std_listener = StdUnixListener::bind("/path/to/the/socket")?;
std_listener.set_nonblocking(true)?;
let listener = UnixListener::from_std(std_listener)?;

Panics

This function panics if it is not called from within a runtime with IO enabled.

The runtime is usually set implicitly when this function is called from a future driven by a tokio runtime, otherwise runtime can be set explicitly with Runtime::enter function.

pub fn into_std(self) -> Result<UnixListener>

Available on non-loom only.

Turns a tokio::net::UnixListener into a std::os::unix::net::UnixListener.

The returned std::os::unix::net::UnixListener will have nonblocking mode set as true. Use set_nonblocking to change the blocking mode if needed.

Examples

let tokio_listener = tokio::net::UnixListener::bind("/path/to/the/socket")?;
let std_listener = tokio_listener.into_std()?;
std_listener.set_nonblocking(false)?;

pub fn local_addr(&self) -> Result<SocketAddr>

Available on non-loom only.

Returns the local socket address of this listener.

pub fn take_error(&self) -> Result<Option<Error>>

Available on non-loom only.

Returns the value of the SO_ERROR option.

pub async fn accept(&self) -> Result<(UnixStream, SocketAddr)>

Available on non-loom only.

Accepts a new incoming connection to this listener.

Cancel safety

This method is cancel safe. If the method is used as the event in a tokio::select! statement and some other branch completes first, then it is guaranteed that no new connections were accepted by this method.

pub fn poll_accept( &self, cx: &mut Context<'_>, ) -> Poll<Result<(UnixStream, SocketAddr)>>

Available on non-loom only.

Polls to accept a new incoming connection to this listener.

If there is no connection to accept, Poll::Pending is returned and the current task will be notified by a waker. Note that on multiple calls to poll_accept, only the Waker from the Context passed to the most recent call is scheduled to receive a wakeup.

Trait Implementations

impl AsFd for UnixListener

Available on non-loom only.

fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor.

impl AsRawFd for UnixListener

Available on non-loom only.

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for UnixListener

Available on non-loom only.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TryFrom<UnixListener> for UnixListener

Available on non-loom only.

fn try_from(stream: UnixListener) -> Result<Self>

Consumes stream, returning the tokio I/O object.

This is equivalent to UnixListener::from_std(stream).

type Error = Error

The type returned in the event of a conversion error.